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

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

最近在部署一个 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 不会区分文件名的大小写，这就导致了：

1. 在 Windows/Mac 上开发时，一切正常
2. 文件被提交为 `httpClient.ts`（小写）
3. 但在 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`，这在实际开发中带来了便利，但也埋下了隐患。

## 最佳实践总结

1. **统一命名规范**
   - 类文件使用 PascalCase: `HttpClient.ts`
   - 工具函数使用 camelCase: `formatDate.ts`
   - 配置文件使用 kebab-case: `app-config.ts`

2. **团队协作约定**
   - 新成员入职时强调文件名规范
   - 代码审查时注意文件名大小写
   - 使用工具自动化检查

3. **跨平台开发策略**
   - 主要开发环境尽量与生产环境一致（推荐使用 Linux 容器）
   - 定期在 CI/CD 环境中测试构建
   - 建立快速反馈机制

## 结语

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

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

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

---

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

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

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

问题根源：大小写敏感性的差异

深入理解：为什么会有这种差异？