Build failed 不是原因，只是最后结果

开发运行和生产构建不一样

dev       为了快速开发，边改边刷新
build     完整检查并生成可发布文件
deploy    把构建结果放到线上

所以 localhost 正常，不保证 build 成功；build 成功，也不保证线上运行时环境变量齐全。

先确认平台执行了什么命令

日志开头可能显示：

Running: pnpm install
Running: pnpm build

如果项目实际使用 npm、命令是 npm run build，平台却执行 pnpm，先修构建配置，不要改 React。

把日志分成四个阶段

安装依赖

npm install
pnpm install
pip install -r requirements.txt

错误常与锁文件、版本、网络和依赖冲突有关。

编译和类型检查

Type error
SyntaxError
Cannot find module

通常带文件和行号。

生成产物

框架渲染页面、打包资源、输出 dist 等目录。

发布或启动

上传产物、启动服务、健康检查。这里失败可能是端口、启动命令或运行环境变量。

一条日志逐词读

src/App.tsx:58:7
Type error: Property 'name' does not exist on type 'Project'.

src/App.tsx     文件
58              行
7               列
Type error      类型检查发现矛盾
name            代码正在读取的字段
Project         TypeScript 认为当前对象应该符合的类型

先打开第 58 行，查看变量实际类型和数据返回，不要立刻给 Project 随便加一个 name。

为什么先修第一条具体错误

Cannot find module './MessageCard'
Property 'message' does not exist
Failed to render page
Build failed

第一个模块缺失可能引起后面全部连锁失败。最后一句只是总结。

常见“本地正常，线上失败”

文件名大小写

import MessageCard from './messageCard'
真实文件 MessageCard.tsx

某些本地文件系统可能宽松，Linux 构建严格区分大小写。

Node 或 Python 版本不同

本地使用新版本语法，平台运行旧版本。查看 package.json engines、.nvmrc、runtime 配置或平台设置。

环境变量缺失

本地 .env 有 DATABASE_URL，线上没有。构建或启动时会失败。

锁文件和包管理器不一致

项目有 pnpm-lock.yaml，平台却运行 npm。依赖结果可能不同。

构建输出目录错误

Vite 常见 dist，VitePress 默认 .vitepress/dist。平台发布了错误文件夹，就可能出现空站点或 404。

依赖只装在电脑全局

本地能找到命令，平台干净环境找不到。项目必须在 package.json 或对应清单声明依赖。

用本地构建复现

先查看 package.json scripts，再运行项目对应命令：

pnpm build

如果本地也失败，优先在本地修，反馈更快。

如果本地成功、线上失败，比较：

包管理器和锁文件
Node / Python 版本
构建命令
环境变量
工作目录
输出目录
操作系统大小写

交给 AI 的构建排错材料

部署平台：
构建命令：
输出目录：
包管理器和锁文件：
本地 build 是否成功：
日志第一条具体错误：
错误前后 15 行：
相关文件和行号：

不要只发日志最后一句 Command exited with code 1。

修完怎样验收

本地 build 成功
部署平台 install 成功
部署平台 build 成功
发布阶段成功
公开网址返回新版本
关键功能真实操作成功

本地 npm run dev 正常，是否证明线上构建一定能通过？

答案：不能。dev 可能跳过完整类型检查或使用不同环境；还要运行生产 build，并比较线上包管理器、版本、变量和输出目录。