无服务器部署与 CI CD 自动化
11.5 构建优化排查
Tip
本地开发是"宽容"的慈母，线上构建是"严苛"的教官。
1. 为什么要学这个?
典型惨案：
你在本地 npm run dev 跑得飞起，功能一切正常。
一推到 Vercel，构建失败 (Build Failed)。
你对着红色的报错日志发呆，不知道为什么"同样的代码"会有两副面孔。
原因：本地为了让你开发爽，隐藏了很多隐患（如类型错误、大小写问题）。Vercel 的 Linux 构建环境则是零容忍的。
2. 核心概念：Strict Mode (严格模式)
CI/CD 环境默认执行最严格的检查：
- TypeScript Check: 所有类型必须正确，不能有
any(除非配置推翻)。 - ESLint Check: 代码风格必须符合规则。
- Case Sensitivity: Linux 区分文件名大小写，而 Windows/Mac 不区分。
3. 常见报错与解法
1. The Case Sensitive Ghost (大小写幽灵)
- 现象：
Module not found: Can't resolve './header' - 原因：
- 文件名叫
Header.tsx。 - 代码里写
import Header from './header'。 - Windows/Mac 觉得没问题 (忽略大小写)。
- Vercel (Linux) 觉得这是两个文件，直接报错。
- 文件名叫
- 解法：
git mv header.tsx Header.tsx(或者统一全小写)。
2. TypeScript Error
- 现象：
Property 'id' does not exist on type 'User'。 - 原因：本地 dev 模式可能只是警告，build 模式是报错。
- 解法：永远不要掩耳盗铃。不要用
// @ts-ignore，老老实实定义 Interface。
3. Build Timeout (构建超时)
- 现象：
Command exited with signal "SIGKILL"。 - 原因：内存爆了，或者死循环。常见于生成了几千个静态页面 (SSG)。
- 解法：检查
generateStaticParams是否返回了太多数据。
4. 解决方案 (HOW)
本地模拟构建
永远不要依赖 Vercel 来发现低级错误。 在 push 之前，请在本地运行一次 "准生产环境" 构建：
# 这行命令会暴露所有隐患
npm run build
如果本地能过，Vercel 99% 也能过。如果你本地都报错，就别去浪费 Vercel 的构建时长了。
排查流程图
graph TD
Build["开始构建"] --> Install["npm install"]
Install --> Check{"依赖安装成功?"}
Check -- No --> Fail["报错: Module not found"]
Check -- Yes --> TS["TypeScript 检查"]
TS -- Error --> FailTS["报错: Type Error"]
TS -- Pass --> Lint["ESLint 检查"]
Lint -- Error --> FailLint["报错: Lint Error"]
Lint -- Pass --> Compile["Next.js 编译"]
Compile --> Success["构建成功"]
style Fail fill:#ffcdd2,stroke:#c62828
style FailTS fill:#ffcdd2,stroke:#c62828
style FailLint fill:#ffcdd2,stroke:#c62828
style Success fill:#c8e6c9,stroke:#2e7d32
5. 真实案例
Story
"Works on My Machine" (在我的机器上是好的)
一个刚转前端的工程师被 Vercel 折磨了一整天。
他的组件文件夹叫 Components (首字母大写)，但他代码里引用的是 import btn from '@/components/Btn' (小写)。
在他的 Mac 上，一切正常。
但每次推送到 Vercel，都提示找不到文件。
他甚至怀疑是 Vercel 的 Bug，给客服发了工单。
客服只回了一句话："Linux filesystem is case-sensitive."
Vibe 心法：
敬畏操作系统之间的差异。
养成全小写 (kebab-case) 的文件名习惯（如 user-profile.tsx），是避开跨平台幽灵的最好护身符。
6. 本章小结
- Pre-commit：本地先
npm run build，通过了再 push。 - 文件名规范：统一全小写，杜绝大小写问题。
- 直面红色：IDE 的红色波浪线不是为了烦你，是为了救你。