.gitignore 完整範本：20 種常見開發場景與最佳實踐指南

在 Git 的版本控制世界裡，有一種檔案被稱為「開發者的保命符」，那就是 .gitignore。

如果你曾經在 Pull Request 中看到成千上萬行的 node_modules 變動，或者在公開的 Repository 中不小心洩漏了包含 AWS Access Key 的 .env 檔案，那你一定明白忽略「不該進入版本控制的檔案」有多麼重要。一個撰寫良好的 .NET、Python 或 Node.js 專案，其核心價值之一就在於其 .gitignore 的完整性。

本文將為你提供一份極其詳盡的 .gitignore 完整範本，涵蓋 20 種常見的開發場景，並深入探討如何撰寫高效、專業的忽略規則。如果你覺得手寫規則太過繁瑣，也可以直接使用 Super Tools gitignore 產生器 來快速生成專屬你的設定檔。

為什麼 .gitignore 是開發者的保命符？

在深入範本之前，我們必須先理解為什麼我們需要忽略某些檔案。Git 的設計初衷是追蹤「原始碼」的變動，而非追蹤「執行結果」或「個人設定」。

避免 Repository 肥大化 (Repo Bloat)

許多開發工具（如編譯器、套件管理員）會產生大量的暫存檔或依賴套件。例如 node_modules 或 venv 資料夾，其檔案數量與體積可能高達數百 MB 甚至 GB 等級。如果將這些檔案提交到 Git，會導致 git clone 變得極慢，且每一次的 git push 都會耗費大量的頻寬與時間。

防止敏感資訊外洩 (Security Risks)

這是最致命的錯誤。開發環境中經常需要 .env、config.json 或 credentials.xml 等檔案來存放資料庫密碼、API Token 或私鑰。一旦這些檔案被推送到 GitHub 等公開平台，你的伺服器可能在幾分鐘內就被駭客接管。

減少 Merge Conflict (衝突) 的發生

開發者마다 使用不同的編輯器（VS Code, IntelliJ, Vim）。每個編輯器都會產生自己的設定檔（如 .vscode/ 或 .idea/）。如果這些檔案被納入版本控制，當團隊成員使用不同工具時，會頻繁觸發無意義的檔案衝突，嚴重影響開發效率。

決策一個專案是否專業，往往取決於其 .gitignore 是否能將「噪音」與「核心程式碼」完美分離。

掌握 .gitignore 語法核心規則

撰寫 .gitignore 並不難，但要寫得精準，你需要理解 Git 的匹配邏輯。

萬用字元與路徑匹配

  • *：匹配零個或多個字元。例如 *.log 會忽略所有以 .log 結尾的檔案。
  • ?：匹配單個字元。例如 file?.txt 會匹配 file1.txt 但不會匹配 file12.txt。
  • [abc]：匹配括號內的任何一個字元。
  • **：用於遞迴匹配目錄。例如 logs/**/*.log 會忽略 logs/ 目錄下所有子目錄中的 .log 檔案。

目錄與檔案的區別

  • /debug.log：僅忽略根目錄下的 debug.log，不會影響 src/debug.log。
  • debug.log：忽略專案中任何地方出現的 debug.log。
  • temp/：忽略整個 temp 目錄及其所有內容。

排除規則 (Negation)

這是最進階且實用的技巧。如果你想忽略所有 .txt 檔，但唯獨想保留 important.txt，你可以使用 ! 符號：

*.txt
!important.txt

註解與結構化

使用 # 開頭的行會被視為註解。在撰寫大型 .gitignore 時，強烈建議使用註解來區分不同的分類（例如：OS、IDE、Language），這能讓後續接手的同事（或是三個月後的你自己）一眼看懂規則的意圖。

20 種常見開發場景的 .gitignore 範本

以下我將開發場景分為五大類別，你可以根據你的專案需求，直接複製並整合到你的 .gitignore 中。

第一類：作業系統與環境雜訊 (OS & Environment)

這些檔案是由作業系統自動產生的，與程式碼邏輯完全無關，應優先忽略。

  1. macOS (Apple 系統)
    • .DS_Store：macOS 用於儲存資料夾自訂屬性的隱藏檔。
    • .AppleDouble：處理檔案系統屬性的副檔名。 ．

  2. Windows 系統

    • Thumbs.db：Windows 用於快取縮圖的資料庫檔案。
    • desktop.ini：儲存資料夾自訂設定的檔案。

  3. Linux 系統

    • *~：許多 Linux 編輯器（如 Emacs）產生的暫存檔。

第二類：編輯器與 IDE 設定 (IDEs & Editors)

避免不同開發者之間的開發工具設定互相覆蓋。

  1. Visual Studio Code

    • .vscode/：包含專案特定的擴充功能建議、除錯設定（除非團隊共用此設定）。
    • *.code-workspace：個人化的工作區設定。

  2. IntelliJ / JetBrains 系列

    • .idea/：IntelliJ, WebStorm, PyCharm 等產生的專案索引與設定。

  3. Vim / Emacs

    • *.swp：Vim 在編輯時產生的交換檔（Swap files）。
    • .netrwhist：Netrw 插件的歷史紀錄。

第三類：前端開發與 JavaScript 生態系 (Frontend & JS)

前端開發是 .gitignore 需求最密集的領域。

  1. Node.js / NPM

    • node_modules/：絕對不能提交。這是依賴套件的存放地，體積巨大且可透過 npm install 重新生成。
    • npm-debug.log*：NPM 執行失敗時產生的錯誤日誌。

  2. 打包工具 (Webpack, Vite, Rollup)

    • dist/：編譯後的產出目錄。
    • build/：打包後的靜態檔案目錄。
    • .cache/：打包工具產生的快取。

  3. React / Vue / Angular

    • coverage/：單元測試產生的覆蓋率報告。

第四類：後端開發語言 (Backend Languages)

不同語言有其特定的編譯產物與虛擬環境。

  1. Python

    • __pycache__/：Python 編譯後的 Bytecode 目錄。 ．
    • *.pyc：編譯後的 Python 檔案。
    • .venv/ 或 venv/：Python 的虛擬環境資料夾。
    • .pytest_cache/：Pytest 測試工具產生的快取。

  2. Java / Kotlin

    • *.class：Java 編譯後的類別檔案。
    • *.jar：Java 封裝後的執行檔。
    • .gradle/：Gradle 建置工具的快取與設定。

  3. C / C++

    • *.o：編譯後的物件檔（Object files）。
    • *.exe：Windows 平台的執行檔。
    • *.out：Linux/Unix 的執行檔。

  4. Go (Golang)

    • bin/：編譯後的二進位執行檔。

  5. Ruby

    • .bundle/：Bundler 的配置。
    • log/：Ruby on Rails 產生的日誌。

第五類：安全性、日誌與其他 (Security, Logs & Others)

  1. 環境變數與機密 (Security - 極重要)

    • .env：包含資料庫密碼、API Key 的環境變數檔。
    • .env.local：本地開發用的環境變數。
    • *.pem / *.key：SSL/TLS 憑證與私鑰。

  2. 日誌檔案 (Logs)

    • *.log：所有的日誌輸出。
    • npm-debug.log：NPM 錯誤日模。

  3. 資料庫與檔案儲存 (Database & Storage)

    • *.sqlite：SQLite 資料庫檔案（除非是測試用的輕量資料庫）。
    • *.db：通用資料庫格式。

  4. Docker

    • .dockerignore 雖然是另一個檔案，但有時我們會忽略 Docker 產生的本地 volume 數據。

  5. Unity / Game Development

    • Library/：Unity 產生的專案資源索引（極大且可重新生成）。
    • Temp/：Unity 暫存目錄。
    • UserSettings/：開發者的個人編輯器設定。

  6. Flutter / Dart

    • .dart_tool/：Dart 工具產生的快取。
    • build/：Flutter 編譯後的產出。

綜合範例：一個標準的 Web 專案 .gitignore

如果你正在開發一個典型的 Full-stack 專案（例如使用 Node.js + React），你可以參考以下結構化後的範本：

# ==========================================
# OS Specific Files
# ==========================================
.DS_Store
Thumbs.db
desktop.ini

# ==========================================
# IDE & Editor Configs
# ==========================================
.vscode/
.idea/
*.swp
*.swo

# ==========================================
# Dependencies & Package Managers
# ==========================================
node_modules/
jspm_packages/
.npm/

# ==========================================
# Build Outputs & Dist
# ==========================================
dist/
build/
out/
.cache/
coverage/

# ==========================================
# Environment & Secrets (CRITICAL!)
# ==========================================
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
*.pem
*.key
*.secret

# ==========================================
# Logs & Debugging
# ==========================================
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
logs/

# ==========================================
# Python (if used in backend)
# ==========================================
__pycache__/
*.py[cod]
venv/
.venv/

比較表：哪些檔案「絕對不能」進入 Git？

檔案類型 範例 為什麼要忽略？ 忽略後的後果
敏感資訊 .env, *.key 防止帳號密碼、API Key 外洩導致資安事故。 雖然需要手動建立，但安全性大幅提升。
依賴套件 node_modules/, venv/ 檔案數量極大，會導致 Git 效能大幅下降。 團隊成員只需執行 npm install 即可重建。
編譯產物 dist/, *.exe, *.class 這些是從原始碼產生的，提交它們沒有意義且造成衝突。 每次 Build 產生的檔案保持乾淨，只追蹤原始碼。
個人設定 .vscode/, .idea/ 避免開發者之間的工具偏好互相干擾。 每個開發者能保有自己習慣的開發環境。
系統暫存 .DS_Store, Thumbs.db 這些是作業系統的「噪音」，與專案邏輯無關。 Git 歷史紀錄會變得非常乾淨，Diff 易於閱讀。

進階技巧：如何處理「已經被追蹤」的檔案？

新手常遇到一個最頭痛的問題：「我明明在 .gitignore 加入了 .env，但 Git 還是持續追蹤它的變動，怎麼辦？」

這是因為 .gitignore 只對「尚未被追蹤 (Untracked)」的檔案生效。如果該檔案已經存在於 Git 的索引 (Index) 中，你必須先將它從快取中移除。

請依照以下步驟操作：

  1. 先將變動存檔（確保你的 .gitignore 已經寫好）。

  2. 從 Git 快取中移除檔案（這不會刪除你硬碟上的實體檔案）： ```bash # 移除單一檔案 git rm --cached .env

    或者，如果你想重設整個專案的追蹤狀態（最常用於處理大量誤入檔案）

    git rm -r --cached . 3. **重新加入所有檔案**：bash git add . 4. **提交變更**：bash git commit -m "Fix: Remove ignored files from version control" ```

這樣一來，Git 就會重新掃描 .gitignore 並根據新規則來決定哪些檔案應該被忽略。

維護 .gitignore 的最佳實踐與建議

  1. 不要等到出事才寫：在專案初始化（git init）的第一秒，就應該建立好 .gitignore。
  2. 保持結構化：使用註解將規則分類（如本文所示），這對於長期維護的專案至關重要。
  3. 使用 Global Gitignore：如果你希望所有專案都自動忽略 .DS_Store，你可以設定一個全域的忽略檔： bash git config --global core.excludesfile ~/.gitignore_global
  4. 善用自動化工具：不要試圖從零開始寫所有的規則。對於複雜的專案，使用 Super Tools gitignore 產生器 可以節省大量時間，並確保沒有遺漏常見的陷阱。
  5. 定期檢查：隨著專案規模擴大，新的工具或框架可能會引入新的暫存檔，記得定期檢查你的 .gitignore 是否需要更新。

如果你對開發流程、自動化部署或各種程式開發工具感興趣，歡迎探索 Super Tools 集合，這裡有更多能提升開發效率的神兵利器。

FAQ：關於 .gitignore 的常見問題

Q1: 我可以針對同一個資料夾，忽略所有檔案但保留其中一個嗎？

可以。你可以先忽略整個資料夾，然後使用 ! 符號排除特定檔案。

logs/*
!logs/important.log

Q2: .gitignore 會影響到我的子目錄嗎？

會的。預設情況下，.gitignore 中的規則會遞迴地應用到專案的所有子目錄中，除非你使用了路徑開頭的 / 來限制範圍。

Q3: .gitignore 與 .git/info/exclude 有什麼區別？

.gitignore 會被提交到版本庫，所有團隊成員都會共用；而 .git/info/exclude 僅存在於你本地的電腦，不會被推送到遠端，適合存放「只有你個人會用到」的忽略規則。

Q4: 我應該把 .gitignore 提交到 Git 倉庫中嗎？

絕對應該。 .gitignore 是專案的一部分，提交它能確保所有開發成員、CI/CD 伺服器都遵循相同的忽略規則，維持環境的一致性。

Q5: 如果我不小心把 .env 推送到 GitHub 了，該怎麼辦？

這是一個嚴重的資安事件。僅僅刪除檔案並提交是不夠的，因為檔案仍存在於 Git 的歷史紀錄中。你必須使用工具（如 BFG Repo-Cleaner 或 git filter-repo）來徹底從歷史中抹除該檔案，並且立即更換所有已洩漏的密鑰與密碼。

Q6: 為什麼我的 .gitignore 設定了卻沒生效？

最常見的原因是該檔案已經被 Git 追蹤（Tracked）了。請參考本文「處理已經被追蹤的檔案」章節，使用 git rm --cached 指令來重新處理。

結論

撰寫一個完美的 .gitignore 檔案，是從「寫程式的人」轉變為「專業軟體工程師」的重要里程碑。它不僅僅是一份清單，更是一份關於專案架構、安全性與團隊協作規範的聲明。

透過正確的分類與語法運用，你可以確保你的版本控制紀錄保持乾淨、高效，並將開發者的注意力集中在真正有價值的程式碼變動上。下次在建立新專案時，別忘了先檢查你的 .gitignore 範本是否完整！