Cấu hình .gitignore chuẩn từ đầu: Tránh push nhầm .env, node_modules và file hệ thống
Hướng dẫn cấu hình .gitignore chuẩn cho dự án Git, Node.js và Next.js: cú pháp pattern, bảo vệ file .env, bỏ qua node_modules, xử lý file đã tracked và kiểm tra rule hiệu quả.
ShanverseUpdated 8 min read— viewsLoading views
Git
Secret Management
Một lần git add . thiếu kiểm tra có thể đưa .env, node_modules, log hoặc file cấu hình cá nhân vào commit. Với file lớn, hậu quả là repository nặng. Với API key và token, hậu quả nghiêm trọng hơn: xóa file trong commit sau không xóa secret khỏi lịch sử.
Bài này hướng dẫn cách xây dựng .gitignore chuẩn cho dự án JavaScript, Node.js và Next.js, đồng thời giải thích cách xử lý khi file đã bị Git theo dõi.
.gitignore làm gì?
.gitignore chứa các pattern cho Git biết những file
Comments
chưa được theo dõi
nào nên được bỏ qua.
Ví dụ:
Sau khi lưu file, chạy:
Các file khớp pattern sẽ không xuất hiện trong danh sách Untracked thông thường.
Tạo .gitignore từ đầu
Tại thư mục gốc của repository:
Thêm cấu hình cơ bản cho Node.js/Next.js:
Không phải dự án nào cũng cần mọi rule. Hãy giữ những pattern phù hợp với công cụ của bạn và ghi chú để team hiểu lý do.
Vì sao không commit node_modules?
node_modules không nên nằm trong repository vì:
Có thể chứa hàng chục nghìn file.
Làm clone, diff và CI chậm hơn.
Có thể khác nhau giữa hệ điều hành.
Có thể tái tạo từ package.json và lockfile.
Bỏ qua thư mục:
Nhưng nên commit lockfile phù hợp:
Lockfile giúp máy cá nhân và CI cài cùng cây dependency. Đừng bỏ qua lockfile chỉ vì nó được tạo tự động.
Bảo vệ file .env
File .env thường chứa:
Bỏ qua các file môi trường cục bộ:
Nếu muốn bỏ qua mọi file bắt đầu bằng .env:
Khi dùng pattern rộng, tạo ngoại lệ để commit file mẫu:
Commit .env.example, không commit secret
Tạo file .env.example chỉ chứa tên biến và giá trị giả:
File này giúp người khác biết dự án cần biến nào mà không làm lộ credential thật.
Tài liệu setup có thể hướng dẫn:
Bỏ qua file hệ thống và editor
macOS thường tạo:
Windows có thể tạo:
Editor và IDE có thể tạo metadata riêng:
Tuy nhiên, team có thể muốn commit một phần cấu hình editor dùng chung, ví dụ extensions khuyến nghị hoặc settings format. Khi đó dùng ngoại lệ:
Hiểu cú pháp pattern
Bỏ qua một file cụ thể
Bỏ qua một thư mục
Dấu / cuối giúp diễn đạt rõ đây là thư mục.
Chỉ khớp ở thư mục gốc
Pattern này không bỏ qua src/config.local.js.
Khớp file theo phần mở rộng
Khớp ở nhiều cấp thư mục
Tạo ngoại lệ bằng !
Git đọc rule từ trên xuống; rule sau có thể ghi đè rule trước.
Comment và dòng trống
Dòng bắt đầu bằng # là comment.
.gitignore ở đâu?
Thông thường, đặt .gitignore ở root của repository để team cùng sử dụng.
Bạn cũng có thể đặt .gitignore trong thư mục con. Rule ở đó áp dụng cho thư mục đó và các thư mục con.
Với file riêng của máy cá nhân mà không nên ép cả team dùng, cấu hình global ignore:
Ví dụ ~/.gitignore_global:
Global ignore phù hợp với file hệ điều hành và công cụ cá nhân; .gitignore trong dự án phù hợp với output và secret liên quan đến dự án.
Khi file đã bị Git theo dõi
Đây là nhầm lẫn phổ biến nhất: bạn thêm node_modules/ hoặc .env vào .gitignore, nhưng git status vẫn hiển thị thay đổi.
Lý do: .gitignore chỉ tác động lên file Untracked. File đã commit hoặc stage vẫn là Tracked.
Ngừng theo dõi một file nhưng giữ trên máy
Ngừng theo dõi một thư mục
Sau đó:
Làm mới toàn bộ index theo .gitignore
Nếu nhiều file đã bị tracked sai:
Đọc kỹ danh sách staged trước khi commit:
Rồi commit:
Lệnh git rm --cached chỉ xóa file khỏi Git index; không xóa bản local khi dùng đúng tùy chọn --cached.
Kiểm tra một file bị ignore bởi rule nào
Dùng:
Kết quả cho biết:
File .gitignore chứa rule.
Số dòng.
Pattern đã khớp.
Đường dẫn được kiểm tra.
Kiểm tra nhiều file:
Liệt kê các file ignored trong trạng thái ngắn:
Khi ngoại lệ ! không hoạt động
Giả sử bạn viết:
Git đã bỏ qua cả thư mục public, nên có thể không duyệt vào trong để tìm ngoại lệ. Hãy mở lại thư mục rồi chọn file:
Nguyên tắc: để include lại một file, các thư mục cha của nó cũng phải có thể được Git duyệt.
Có nên dùng git add -f?
Lệnh sau ép Git stage file ignored:
Đây là thao tác nguy hiểm với secret. Chỉ dùng -f khi bạn chắc chắn file bị ignore quá rộng và nội dung an toàn, ví dụ một fixture test cần commit.
Tốt hơn, hãy chỉnh rule và thêm ngoại lệ rõ ràng:
.gitignore không xóa secret khỏi lịch sử
Nếu secret đã được commit:
Thu hồi hoặc rotate secret ngay lập tức.
Xóa file khỏi tracking bằng git rm --cached.
Thêm rule phù hợp vào .gitignore.
Commit thay đổi.
Nếu cần xóa khỏi lịch sử, phối hợp với team và dùng công cụ làm sạch lịch sử phù hợp.
Thông báo cho người liên quan vì rewrite history ảnh hưởng clone và branch hiện có.
Không nên xem việc rewrite history là lý do để trì hoãn rotate secret. Secret đã lộ cần được coi là không còn an toàn.
Mẫu .gitignore đề xuất cho Next.js
Điều chỉnh theo package manager, framework và chính sách của team. Không sao chép một template dài mà không đọc từng rule.
Quy trình an toàn trước commit và push
Checklist .gitignore
Tạo .gitignore trước commit đầu tiên.
Bỏ qua dependencies như node_modules/.
Bỏ qua .env và các file môi trường local.
Commit .env.example không chứa secret thật.
Bỏ qua output như .next/, dist/, build/ và coverage/.
Bỏ qua log, cache và file hệ điều hành.
Không bỏ qua lockfile của package manager.
Kiểm tra rule bằng git check-ignore -v.
Xử lý riêng các file đã tracked bằng git rm --cached.
Rotate ngay secret từng bị commit.
Tổng kết
Một .gitignore tốt giúp repository nhỏ, sạch và an toàn hơn, nhưng chỉ hiệu quả khi bạn hiểu ba điều:
Pattern chỉ tự động bỏ qua file chưa được theo dõi.
File đã tracked phải được xóa khỏi index bằng git rm --cached.
Secret đã commit cần được rotate; xóa file không thể thu hồi secret.
Hãy tạo .gitignore từ đầu, commit file mẫu như .env.example, và kiểm tra staging area trước mọi commit. Đó là lớp phòng vệ đơn giản nhưng rất hiệu quả trước những lần git add . vội vàng.
Table of contents(27)
Codeplain text
1node_modules/2.env3.next/4*.log5.DS_Store
Codeplain text
1# Dependencies2node_modules/34# Environment variables5.env6.env.local7.env.development.local8.env.test.local9.env.production.local1011# Next.js12.next/13out/1415# Build output16dist/17build/1819# Test and coverage20coverage/2122# Logs23*.log24npm-debug.log*25yarn-debug.log*26yarn-error.log*27pnpm-debug.log*2829# Package manager caches30.npm/31.pnpm-store/32.yarn/cache/33.yarn/unplugged/3435# TypeScript36*.tsbuildinfo37next-env.d.ts3839# IDE and editors40.vscode/41.idea/42*.swp4344# Operating system45.DS_Store46Thumbs.db4748# Local certificates and keys49*.pem50*.key
1# 1. Kiểm tra trạng thái2gitstatus34# 2. Xem cả file ignored nếu cần5gitstatus--short--ignored67# 3. Stage các file có chủ đích8gitaddsrc/package.jsonpackage-lock.json.gitignore910# 4. Kiểm tra snapshot sắp commit11gitdiff--staged1213# 5. Kiểm tra tên file nhạy cảm14gitdiff--staged--name-only1516# 6. Commit17gitcommit-m"chore: configure gitignore"1819# 7. Kiểm tra lại trước khi push20gitstatus21gitlog--oneline-3
Related posts
More articles with related topics and technologies.
Hướng dẫn quản lý secrets với .env và Git: phân loại cấu hình, gitignore, env example, hooks, secret scanning, CI/CD, Next.js, Docker, rotation và incident response.
Hướng dẫn bảo mật Git repository khi lộ API key hoặc password trên GitHub: rotate credential, xóa lịch sử với git-filter-repo/BFG, force push, xác minh và phối hợp team.
Hướng dẫn Git Aliases và .gitconfig thực chiến: alias an toàn, log đẹp, cấu hình pull/push/rebase, includeIf cho tài khoản work/personal, bảo mật và chia sẻ dotfiles.
