从 Vercel 构建失败谈 Git 大小写敏感性问题：一个容易被忽视的跨平台陷阱

最近开发ReactPress的时候，本地构建一切正常，但一到 Vercel 就报错？这可能是 Git 大小写敏感性在作祟。本文将分享一个真实的故障排查案例，帮助你避免这个隐蔽的跨平台兼容性问题。

ReactPress地址：github.com/fecommunity... 欢迎Star

问题背景：诡异的构建失败

最近在部署一个 React 项目到 Vercel 时，遇到了一个令人困惑的问题：

bash 复制代码

# 本地构建（成功）
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 的配置：

bash 复制代码

# 检查 Git 大小写配置
git config core.ignorecase
# 返回: true

当 core.ignorecase=true 时，Git 不会区分文件名的大小写，这就导致了：

在 Windows/Mac 上开发时，一切正常
文件被提交为 httpClient.ts（小写）
但在 Linux 构建环境中，导入语句找不到对应的文件

解决方案：三步修复法

第一步：诊断问题

bash 复制代码

# 查看实际文件名
find . -name "*httpclient*" -type f
# 输出: ./src/api/httpClient.ts

# 查看 Git 记录的文件名
git ls-files | grep -i httpclient
# 输出: src/api/httpClient.ts

第二步：修复文件名

bash 复制代码

# 临时启用大小写敏感
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

第三步：验证修复

bash 复制代码

# 在 GitHub 上确认文件名已更正
# 等待 Vercel 重新部署
# 构建应该成功通过

预防措施：建立防护网

1. 项目级配置

在项目中添加 .gitconfig 文件：

ini 复制代码

[core]
    ignorecase = false

2. ESLint 规则检查

配置 ESLint 检查文件名规范：

javascript 复制代码

// .eslintrc.js
module.exports = {
  rules: {
    'unicorn/filename-case': [
      'error',
      {
        cases: {
          camelCase: true,    // 工具函数：camelCase
          pascalCase: true    // 类/组件：PascalCase
        }
      }
    ]
  }
};

3. CI/CD 流水线检查

在 GitHub Actions 中添加检查：

yaml 复制代码

# .github/workflows/check-filenames.yml
name: Check Filename Case
on: [push, pull_request]

jobs:
  check-case:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check filename consistency
        run: |
          for file in $(find src -name "*.ts" -o -name "*.tsx"); do
            filename=$(basename "$file" .ts | basename "$file" .tsx)
            if [[ $filename =~ [A-Z] ]]; then
              echo "✓ $filename uses PascalCase"
            else
              echo "⚠ $filename - consider using PascalCase for components/classes"
            fi
          done

4. 预提交钩子

使用 Husky 在提交前检查：

bash 复制代码

#!/bin/bash
# .husky/pre-commit
find src -name "*.ts" -o -name "*.tsx" | while read file; do
    base=$(basename "$file")
    if [[ $base =~ ^[a-z] ]] && [[ $base =~ \.(ts|tsx)$ ]]; then
        echo "警告: 建议类文件使用 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
团队协作约定
- 新成员入职时强调文件名规范
- 代码审查时注意文件名大小写
- 使用工具自动化检查
跨平台开发策略
- 主要开发环境尽量与生产环境一致（推荐使用 Linux 容器）
- 定期在 CI/CD 环境中测试构建
- 建立快速反馈机制

结语

这个看似简单的"大小写"问题，实际上涉及操作系统设计、Git 工作原理、团队协作规范等多个层面。在跨平台开发日益普遍的今天，我们需要更加重视这类环境差异导致的问题。

记住：在本地能运行只是第一步，在生产环境能运行才是真正的完成。

希望通过这个案例，你能避免类似的陷阱，建立更健壮的开发工作流。如果你也遇到过类似的跨平台兼容性问题，欢迎在评论区分享你的经验和解决方案！

本文基于真实故障排查经历撰写，项目已成功部署。特别感谢 Vercel 清晰的错误日志，让问题定位变得容易。