在 Windows 建立 .gitignore（含安全與常見範本）

Table of Contents

前言

在 Windows 環境下建立 .gitignore 檔案看似簡單,實際上卻有不少陷阱。Windows 檔案總管的限制、記事本的預設編碼,以及隱藏副檔名的特性,都可能讓初學者踩坑。本文將提供最安全可靠的建立方式,並分享常見的 .gitignore 範本與最佳實踐。

為什麼 Windows 需要特別注意?

常見的三大陷阱

隱藏副檔名問題
- Windows 檔案總管預設隱藏已知檔案類型的副檔名
- 手動建立時可能產生 gitignore.txt 而非 .gitignore
- 結果:Git 無法識別,所有檔案都被追蹤
BOM 編碼問題
- 記事本預設使用 UTF-8 with BOM 編碼
- BOM(Byte Order Mark)是檔案開頭的特殊字元
- 某些 Git 工具可能誤判檔案格式,導致規則失效
檔案總管限制
- Windows 不允許直接建立以點號開頭的檔案
- 嘗試建立時會出現「必須輸入檔案名稱」錯誤
- 需要透過指令或編輯器建立

建立 .gitignore 的安全方式

方法一:PowerShell(推薦)

PowerShell 是 Windows 10/11 的內建工具,提供最可靠的檔案操作:

# 建立空白 .gitignore
New-Item .gitignore -ItemType File -Force

# 或使用縮寫
ni .gitignore -ItemType File -Force

# 從 GitHub 範本下載(以 Node.js 為例)
Invoke-WebRequest https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -OutFile .gitignore

# 或使用縮寫
iwr https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -OutFile .gitignore

優點:

自動使用 UTF-8 無 BOM 編碼
支援以點號開頭的檔案名稱
可直接從網路下載範本
-Force 參數可覆蓋既有檔案

方法二:CMD(傳統方式)

rem 建立空白 .gitignore
type nul > .gitignore

rem 若誤存為 gitignore.txt,可改名
ren gitignore.txt .gitignore

rem 查看檔案內容
type .gitignore

注意事項:

type nul 建立的是空檔案
重導向 > 會覆蓋既有檔案,使用 >> 可附加內容
CMD 預設使用系統編碼,可能不是 UTF-8

方法三:Git Bash(Linux 風格)

# 建立空白 .gitignore
touch .gitignore

# 從 GitHub 下載範本
curl https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore -o .gitignore

# 或使用 wget
wget https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore -O .gitignore

方法四:VS Code / 其他編輯器

步驟:

開啟 VS Code
新增檔案,檔名輸入 .gitignore
右下角選擇編碼為 UTF-8(無 BOM)
儲存檔案

如果無法直接建立:

先用 PowerShell 執行 ni .gitignore
再用 VS Code 開啟編輯

檢查編碼:

VS Code:右下角會顯示編碼格式
若顯示「UTF-8 with BOM」,點擊後選擇「透過編碼儲存」→「UTF-8」

常用 .gitignore 範本

完整範本請參考 GitHub gitignore 專案,以下是常見場景的精簡版:

Node.js / TypeScript

# 依賴套件
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# 編譯輸出
dist/
build/
.next/
out/

# 環境變數與設定
.env
.env.local
.env.*.local

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

# IDE 設定
.vscode/
.idea/
*.swp
*.swo

# 測試覆蓋率
coverage/
.nyc_output/

# 日誌檔案
*.log
logs/

Python

# Byte-compiled / 最佳化檔案
__pycache__/
*.py[cod]
*$py.class

# 虛擬環境
venv/
ENV/
.venv/
env/

# 環境變數
.env

# Jupyter Notebook
.ipynb_checkpoints/

# 測試與覆蓋率
.pytest_cache/
.coverage
htmlcov/

# 日誌
*.log

PHP / Laravel

# Composer 依賴
vendor/

# Laravel 特定
storage/framework/cache/*
storage/framework/sessions/*
storage/framework/views/*
storage/logs/*
bootstrap/cache/*

# 環境變數
.env
.env.backup

# IDE
.idea/
.vscode/

# 作業系統
.DS_Store
Thumbs.db

.NET / C#

# Build 輸出
bin/
obj/
[Dd]ebug/
[Rr]elease/

# Visual Studio
.vs/
*.user
*.suo
*.userosscache
*.sln.docstates

# NuGet 套件
packages/
*.nupkg

# 測試結果
TestResults/
*.trx

# 使用者特定檔案
*.user
*.rsuser

Java / Maven / Gradle

# 編譯輸出
target/
build/
out/

# IDE
.idea/
*.iml
.eclipse/
.classpath
.project

# Gradle
.gradle/
gradle-app.setting

# Maven
dependency-reduced-pom.xml

# 日誌
*.log

編輯器與 IDE(通用)

# Visual Studio Code
.vscode/
*.code-workspace

# JetBrains IDEs
.idea/
*.iml

# Vim
*.swp
*.swo
*~

# Emacs
*~
#*#
.#*

# Sublime Text
*.sublime-project
*.sublime-workspace

全域 .gitignore(個人環境設定)

全域 .gitignore 適合放置個人偏好或作業系統特定的檔案,不應加入專案的 .gitignore。

設定全域 .gitignore

# 設定全域忽略檔案路徑
git config --global core.excludesfile ~/.gitignore_global

# 在 Windows PowerShell 建立檔案
ni ~/.gitignore_global -ItemType File -Force

建議的全域忽略項目

# 作業系統檔案
.DS_Store      # macOS
Thumbs.db      # Windows
desktop.ini    # Windows

# 編輯器設定(依個人偏好)
.vscode/
.idea/

# 暫存檔案
*.tmp
*.temp
*.swp
*.swo
*~

# 日誌檔案
*.log

專案 vs 全域 .gitignore 的區別:

類型	放置位置	適用範圍	範例
專案 .gitignore	專案根目錄	該專案所有貢獻者	`node_modules/`, `dist/`, `.env`
全域 .gitignore	`~/.gitignore_global`	個人所有專案	`.DS_Store`, `.vscode/`, `*.log`

搭配 .gitattributes 管理換行符號

.gitignore 負責忽略檔案,.gitattributes 負責檔案屬性(如換行符號、合併策略)。

避免 CRLF/LF 混亂

建立 .gitattributes 檔案:

# 自動偵測文字檔並標準化換行
* text=auto

# 強制特定檔案類型使用 LF
*.sh text eol=lf
*.bash text eol=lf

# 強制特定檔案類型使用 CRLF
*.bat text eol=crlf
*.cmd text eol=crlf

# 二進位檔案不處理
*.png binary
*.jpg binary
*.pdf binary

換行符號說明:

LF(Line Feed, n):Linux/macOS 標準
CRLF(Carriage Return + Line Feed, rn):Windows 標準
text=auto:Git 自動轉換,提交時轉 LF,檢出時依系統轉換

驗證與排錯

檢查檔案是否被忽略

# 檢查特定檔案是否被忽略
git check-ignore -v path/to/file

# 輸出格式:
# .gitignore:5:*.log    path/to/debug.log
# ↑檔案名    ↑行號 ↑規則  ↑被檢查的檔案

查看生效的 .gitignore 來源

# 查看全域忽略檔案位置
git config --show-origin core.excludesfile

# 查看所有 Git 設定來源
git config --list --show-origin

常見問題排查

問題一:.gitignore 不生效

# 原因:檔案已被 Git 追蹤
# 解決:從索引移除後重新提交
git rm --cached filename
git commit -m "Remove tracked file"

# 若是整個資料夾
git rm -r --cached folder/
git commit -m "Remove tracked folder"

問題二:檔名錯誤(gitignore.txt)

# PowerShell 重新命名
ren gitignore.txt .gitignore

# CMD
ren gitignore.txt .gitignore

# Git Bash
mv gitignore.txt .gitignore

問題三:編碼問題(BOM)

VS Code:右下角點擊編碼 → 選擇「透過編碼儲存」→ 選擇「UTF-8」
Notepad++:編碼 → 轉換為 UTF-8(無 BOM)
PowerShell 重新建立:ni .gitignore -Force

問題四:規則順序錯誤

# ❌ 錯誤:先忽略所有,再嘗試取消忽略
*
!important.txt

# ✅ 正確:先忽略特定類型,再排除例外
*.log
!important.log

.gitignore 語法與最佳實踐

基本語法

# 忽略特定檔案
debug.log

# 忽略所有 .log 檔案
*.log

# 忽略資料夾
node_modules/

# 忽略特定路徑
/config/local.json

# 不忽略(排除規則)
!important.log

# 註解
# 這是註解

進階語法

# ** 匹配任意層級目錄
**/logs/
logs/**/*.log

# ? 匹配單一字元
test?.txt

# [] 匹配字元範圍
*.[oa]
*.[0-9]

# 忽略根目錄的檔案(不含子目錄)
/TODO

# 忽略所有層級的檔案
TODO

最佳實踐

分類組織

# === 依賴套件 ===
node_modules/
vendor/

# === 編譯輸出 ===
dist/
build/

# === 環境變數 ===
.env
.env.local

# === 作業系統 ===
.DS_Store
Thumbs.db

# === IDE ===
.vscode/
.idea/

使用註解說明

# 忽略測試覆蓋率報告(由 jest 產生)
coverage/

# 忽略本地開發環境變數(勿提交敏感資訊)
.env.local

專案特定項目優先

# 專案特定(所有人都需要)
node_modules/
dist/
.env

# 個人偏好(放到全域 .gitignore)
# .vscode/  ← 註解掉,改放 ~/.gitignore_global

避免過度忽略

# ❌ 過度忽略
*
!src/

# ✅ 具體列出
node_modules/
dist/
*.log

常見問題 FAQ

Q1:.gitignore 可以放在子目錄嗎?

A:可以。每個目錄都可以有自己的 .gitignore,規則僅適用於該目錄及子目錄。

project/
├── .gitignore          # 全專案規則
├── src/
│   └── .gitignore      # 僅適用於 src/ 及其子目錄
└── tests/
    └── .gitignore      # 僅適用於 tests/ 及其子目錄

Q2:已提交的檔案可以用 .gitignore 忽略嗎?

A:不行。.gitignore 只對未追蹤的檔案有效。需先移除追蹤:

git rm --cached file.txt
git commit -m "Stop tracking file.txt"

Q3:團隊成員的 IDE 設定檔要忽略嗎?

A:建議做法:

專案 .gitignore:忽略常見 IDE(如 .vscode/, .idea/)
個人 .gitignore_global:忽略個人偏好的工具
部分團隊會提交 .vscode/settings.json 統一設定,但忽略個人化檔案

Q4:.env 檔案要如何處理?

A:最佳實踐:

提交 .env.example(範本,不含敏感資料)
忽略 .env, .env.local(實際使用,含敏感資料)
在 README 說明如何設定

# .gitignore
.env
.env.local
.env.*.local

# .env.example(提交到 repo)
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
API_KEY=your_api_key_here

Q5:為什麼我的 .gitignore 規則不生效?

A:常見原因與解決方法:

原因	檢查方法	解決方法
檔案已被追蹤	`git ls-files filename`	`git rm --cached filename`
檔名錯誤	`ls -la \| grep gitignore`	重新命名為 `.gitignore`
編碼問題	用 VS Code 開啟檢查	改為 UTF-8 無 BOM
語法錯誤	`git check-ignore -v file`	檢查規則寫法

其他建議

專案初始化時直接下載範本

# 初始化 Git repo 並下載 Node.js 範本
git init
iwr https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -OutFile .gitignore

團隊協作注意事項

明確記錄:在 README 說明 .gitignore 涵蓋的內容與維護方式
定期檢視:隨專案演進更新忽略規則
跨平台考量:團隊使用多種 OS 時,需注意路徑分隔符號與換行符號
敏感資料:明確標註哪些檔案含敏感資訊,提供 .example 範本

使用 .gitignore 產生器

gitignore.io:選擇語言/框架/IDE 自動產生
GitHub gitignore 模板庫:官方維護的範本集合

總結

在 Windows 建立 .gitignore 的關鍵重點:

使用 PowerShell ni .gitignore 最安全可靠
確認編碼:UTF-8 無 BOM
驗證檔名:確保是 .gitignore 而非 gitignore.txt
分層管理:專案共用規則放 repo,個人偏好放全域
及早設定:專案初始化時就建立,避免後續清理追蹤檔案

遵循這些原則,就能避免常見的 Windows 陷阱,讓 Git 版本控制更加順暢。

前言