从 Vercel 构建失败谈 Git 大小写敏感性问题：一个容易被忽视的跨平台陷阱
最近开发ReactPress的时候，本地构建一切正常，但一到 Vercel 就报错？这可能是 Git 大小写敏感性在作祟。本文将分享一个真实的故障排查案例，帮助你避免这个隐蔽的跨平台兼容性问题。
ReactPress地址：https://github.com/fecommunity/reactpress 欢迎Star
问题背景：诡异的构建失败
最近在部署一个 React 项目到 Vercel 时，遇到了一个令人困惑的问题：
# 本地构建（成功）
pnpm run build
# ✅ 一切正常# Vercel 构建（失败）
22:32:28.979 src/api/Article.ts(27,43): error TS2307:
Cannot find module './HttpClient' or its corresponding type declarations.
奇怪的是，相同的代码、相同的依赖、相同的构建命令，在本地能够完美构建，但在 Vercel 上却失败了。
问题根源：大小写敏感性的差异
经过排查，发现问题出在文件命名上：
- 实际文件名:
httpClient.ts（首字母小写） - 导入语句:
import HttpClient from './HttpClient';（首字母大写）
这个差异在不同操作系统环境下表现不同：
操作系统差异
| 环境 | 大小写敏感性 | 行为 |
|---|---|---|
| Windows | 不敏感 | ./HttpClient 和 ./httpClient 都能找到文件 |
| macOS | 通常不敏感 | 同上 |
| Linux (Vercel) | 敏感 | 必须精确匹配 ./HttpClient |
Git 的配置陷阱
问题的深层原因在于 Git 的配置：
# 检查 Git 大小写配置
git config core.ignorecase
# 返回: true
当 core.ignorecase=true 时，Git 不会区分文件名的大小写，这就导致了：
- 在 Windows/Mac 上开发时，一切正常
- 文件被提交为
httpClient.ts（小写） - 但在 Linux 构建环境中，导入语句找不到对应的文件
解决方案：三步修复法
第一步：诊断问题
# 查看实际文件名
find . -name "*httpclient*" -type f
# 输出: ./src/api/httpClient.ts# 查看 Git 记录的文件名
git ls-files | grep -i httpclient
# 输出: src/api/httpClient.ts
第二步：修复文件名
# 临时启用大小写敏感
git config core.ignorecase false# 重命名文件（两步法避免冲突）
git mv src/api/httpClient.ts src/api/HttpClient.temp.ts
git mv src/api/HttpClient.temp.ts src/api/HttpClient.ts# 提交修复
git commit -m "fix: correct HttpClient filename case sensitivity"
git push origin feat/reactpresss-config-v2
第三步：验证修复
# 在 GitHub 上确认文件名已更正
# 等待 Vercel 重新部署
# 构建应该成功通过
预防措施：建立防护网
1. 项目级配置
在项目中添加 .gitconfig 文件：
[core]ignorecase = false
2. ESLint 规则检查
配置 ESLint 检查文件名规范：
// .eslintrc.js
module.exports = {rules: {'unicorn/filename-case': ['error',{cases: {camelCase: true, // 工具函数：camelCasepascalCase: true // 类/组件：PascalCase}}]}
};
3. CI/CD 流水线检查
在 GitHub Actions 中添加检查：
# .github/workflows/check-filenames.yml
name: Check Filename Case
on: [push, pull_request]jobs:check-case:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Check filename consistencyrun: |for file in $(find src -name "*.ts" -o -name "*.tsx"); dofilename=$(basename "$file" .ts | basename "$file" .tsx)if [[ $filename =~ [A-Z] ]]; thenecho "✓ $filename uses PascalCase"elseecho "⚠ $filename - consider using PascalCase for components/classes"fidone
4. 预提交钩子
使用 Husky 在提交前检查：
#!/bin/bash
# .husky/pre-commit
find src -name "*.ts" -o -name "*.tsx" | while read file; dobase=$(basename "$file")if [[ $base =~ ^[a-z] ]] && [[ $base =~ \.(ts|tsx)$ ]]; thenecho "警告: 建议类文件使用 PascalCase: $file"fi
done
深入理解：为什么会有这种差异？
历史原因
- Windows: 源于 DOS，设计初衷是用户友好，不区分大小写
- Linux: 源于 UNIX，强调精确和一致性，区分大小写
- macOS: 基于 UNIX，但默认文件系统 HFS+/APFS 通常不区分大小写
Git 的设计选择
Git 为了跨平台兼容性，默认采用 core.ignorecase=true，这在实际开发中带来了便利，但也埋下了隐患。
最佳实践总结
-
统一命名规范
- 类文件使用 PascalCase:
HttpClient.ts - 工具函数使用 camelCase:
formatDate.ts - 配置文件使用 kebab-case:
app-config.ts
- 类文件使用 PascalCase:
-
团队协作约定
- 新成员入职时强调文件名规范
- 代码审查时注意文件名大小写
- 使用工具自动化检查
-
跨平台开发策略
- 主要开发环境尽量与生产环境一致（推荐使用 Linux 容器）
- 定期在 CI/CD 环境中测试构建
- 建立快速反馈机制
结语
这个看似简单的"大小写"问题，实际上涉及操作系统设计、Git 工作原理、团队协作规范等多个层面。在跨平台开发日益普遍的今天，我们需要更加重视这类环境差异导致的问题。
记住：在本地能运行只是第一步，在生产环境能运行才是真正的完成。
希望通过这个案例，你能避免类似的陷阱，建立更健壮的开发工作流。如果你也遇到过类似的跨平台兼容性问题，欢迎在评论区分享你的经验和解决方案！
本文基于真实故障排查经历撰写，项目已成功部署。特别感谢 Vercel 清晰的错误日志，让问题定位变得容易。