GitHub 大小寫問題(Case Sensitivity)

TL;DR

Windows / macOS 預設 case-insensitive filesystem(File.tsx 跟 file.tsx 視為同檔),Git 預設配合 → 改大小寫沒有 stage。Linux / Vercel build 環境 case-sensitive → 同檔被當不同檔 → build fail。解法:git config core.ignorecase false + git mv 強制 rename。

為什麼會踩到

// 你 import 用大寫
import Header from '@/components/Header';

// 但實際檔名是小寫
src/components/header.tsx       // 舊檔

在 Mac/Windows 開發 OK(filesystem 不分大小寫,自動找到 header.tsx)。 Push 到 Vercel(Linux)build 立刻 fail:

Failed to compile. Type error: Cannot find module '@/components/Header'

解法 1:關閉 Git 大小寫忽略

# 單一專案
git config --local core.ignorecase false

# 或全域(所有 repo)
git config --global core.ignorecase false

設完後 git mv / git status 會正確識別大小寫變化。

解法 2:git mv -f 強制 rename

git mv -f OldFileNameCase.tsx newfilenamecase.tsx

-f 強制覆寫,因為 case-insensitive 看起來「目標已存在」。

解法 3:大刀闊斧 重新追蹤

如果上述都失敗,直接清掉 git index 重來:

git rm -r --cached .
git add --all .
git commit -a -m "Versioning untracked files"
git push

等於 「忘掉所有 cached 狀態,重新 add」。安全 — 檔案內容不會動,只是 git 重新識別。

預防(從一開始就統一)

命名規範

團隊定一個規則並 寫進 ESLint:

• 元件檔:PascalCase.tsx(Header.tsx)
• utility / hook:camelCase.ts 或 kebab-case.ts
• CSS module:跟 component 同名(Header.module.css)

ESLint plugin:eslint-plugin-filenames、eslint-plugin-unicorn 內的 filename-case rule。

CI 加防呆

# GitHub Actions
- run: npm run build       # 在 Linux 跑,大小寫錯就會立即 fail

yaml複製

每個 PR 都跑 build,避免 push 到 production 才 fail。

真實案例

我踩過的雷

改了 oldFile.tsx → OldFile.tsx,Mac 上看 git 沒變化以為沒改,push 上去 Vercel build fail。

然後 Stack Overflow 一查才知道:Vercel deploy / build fail. "Failed to compile. Type error: Cannot find module ..."

完整教學

GIT 檔案名稱大小寫修正 - 工作玩樂實驗室