.gitignore 產生指南：按專案型別快速建立忽略規則

.gitignore 是什麼

.gitignore 檔案告訴 Git 哪些檔案/目錄不需要版本控制：

node_modules/       ← 忽略整個目錄
*.log               ← 忽略所有日誌檔案
.env                ← 忽略環境變數檔案
dist/               ← 忽略建構產物

未被追蹤的檔案如果匹配 .gitignore 規則，Git 會自動跳過。已被追蹤的檔案不受影響。

語法規則詳解

基本模式

語法	含義	範例
`*.ext`	匹配所有 .ext 檔案	`*.log`
`dir/`	匹配整個目錄	`node_modules/`
`file`	匹配具體檔案	`.env`
`**`	匹配任意層目錄	`**/test`
`?`	匹配單個字元	`config?.json`
`[abc]`	匹配方括號內任一字元	`file[123].txt`

取反模式 `!`

*.log           ← 忽略所有日誌
!important.log  ← 但保留 important.log

取反模式必須寫在忽略規則之後才有效。

路徑規則

/README.md      ← 僅忽略根目錄的 README.md
README.md       ← 忽略所有路徑下的 README.md
docs/*.pdf      ← 忽略 docs 目錄下的 PDF，不遞迴
docs/**/*.pdf   ← 忽略 docs 所有子目錄下的 PDF

常用專案範本

Node.js

node_modules/
dist/
build/
.next/
.env
.env.local
*.log
coverage/

Python

__pycache__/
*.py[cod]
*.egg-info/
dist/
.venv/
venv/
.env
.pytest_cache/
.mypy_cache/

Java / Spring Boot

target/
*.class
*.jar
*.war
.gradle/
.idea/
*.iml
application-local.yml

IDE / 編輯器

# VS Code
.vscode/

# IntelliJ IDEA
.idea/
*.iml

# macOS
.DS_Store

# Windows
Thumbs.db

使用 gitignore 工具

第一步：開啟工具

造訪 gitignore 工具，進入產生介面。

第二步：選擇專案型別

勾選專案使用的技術棧：

☑ Node.js
☑ Python
☑ Java
☑ Vue / React / Angular

第三步：選擇 IDE

勾選團隊使用的編輯器：

☑ VS Code
☑ IntelliJ IDEA
☑ 其他

第四步：產生並下載

點擊「產生」，工具自動合併所有範本，去除重複規則，產生完整的 .gitignore 檔案。

第五步：放置到專案根目錄

將下載的檔案放到 Git 倉庫根目錄，確保檔名是 .gitignore（注意開頭的點）。

全域 gitignore

除了專案級 .gitignore，還可以設定全域忽略規則（適用於所有倉庫）：

# 設定全域 gitignore 檔案
git config --global core.excludesFile ~/.gitignore_global

# 編輯全域規則
vim ~/.gitignore_global

推薦全域忽略的內容：

# 作業系統檔案
.DS_Store
Thumbs.db

# IDE 設定
.idea/
.vscode/

# 個人工具
.todo

全域規則適合放個人環境相關的檔案，專案級規則適合放專案相關的檔案。

已追蹤檔案的處理

.gitignore 只對未追蹤的檔案生效。如果檔案已經被 Git 追蹤：

# 取消追蹤但保留本地檔案
git rm --cached .env

# 取消追蹤整個目錄
git rm -r --cached node_modules/

# 提交取消追蹤的變更
git commit -m "chore: update gitignore and untrack files"

--cached 參數確保只從 Git 索引中移除，不刪除本地檔案。

常見錯誤

錯誤	原因	解決
規則不生效	檔案已被追蹤	先 `git rm --cached` 取消追蹤
取反不生效	`!` 寫在了忽略規則之前	將 `!` 規則放在對應忽略規則之後
忽略了不該忽略的	模式太寬泛	使用 `/` 限定路徑範圍
忘記忽略 .env	未包含環境變數範本	始終新增 `.env` 到 .gitignore
團隊規則不一致	沒有統一範本	使用工具產生標準範本

.gitignore 與 .gitkeep

忽略目錄後，Git 不會追蹤空目錄。如需保留空目錄結構：

logs/           ← .gitignore 忽略日誌
logs/.gitkeep   ← .gitkeep 佔位，保留目錄

.gitkeep 不是 Git 功能，是社群約定。在空目錄中放一個 .gitkeep 檔案即可。

總結

.gitignore 是專案設定的基礎，正確的忽略規則能避免提交敏感資訊和冗餘檔案。掌握語法規則、常用範本和全域設定，配合 gitignore 工具快速產生，是高效版本控制的第一步。