AI 生成的代码跑不起来？先按这 3 步排查

“跑不起来”这四个字包含三种完全不同的故障，处理顺序也不一样。先分清是哪一种，比直接翻代码快得多。

• 装不上：npm install 就报错，还没到运行这一步
• 起不来：装完了，npm run dev 报错退出
• 起得来但白屏：进程在跑，浏览器里什么都没有

下面按这三类给排查动作。

第一步：版本对不对

AI 生成代码时用的是它训练数据里的版本，你本地是另一个版本，这是最高频的原因。

先看两个数：

node -v
npm -v

再看项目要什么：

cat package.json | grep -A3 engines
cat .nvmrc 2>/dev/null

engines 写 >=20 就是要求 Node 20 以上。用 Node 16 跑，典型报错是：

SyntaxError: Unexpected token '??='
Error: Cannot find module 'node:fs'

这两个不是代码写错了，是语法和内置模块在你的 Node 版本里还不存在。

切换版本：

nvm install 20 && nvm use 20

没有 nvm 就装一个，Windows 用 nvm-windows。切完记得删掉旧的 node_modules 再重装，不同版本装出来的原生模块不通用。

还有一类是包管理器不对。项目里有 pnpm-lock.yaml 就用 pnpm，有 yarn.lock 就用 yarn。用 npm 去装 pnpm 项目，锁文件失效，装出来的依赖树和作者的不一样，报错会非常奇怪。

第二步：依赖装没装上

npm install 输出一堆红色，先看最后几行的错误码，不用从头读。

错误码	真实原因	处理
ERESOLVE	peerDependencies 版本冲突	npm install --legacy-peer-deps
EACCES	权限不足	别用 sudo，改 npm 全局目录或换用户
ETIMEDOUT / ECONNRESET	网络拉不到包	换镜像 --registry=https://registry.npmmirror.com
node-gyp / gyp ERR!	原生模块要编译，缺 Python 或 VS Build Tools	换 Node 版本，或装 windows-build-tools（Win）/ build-essential（Linux）
404 Not Found - GET ...	包名写错，或私有包没配 token	核对包名，检查 .npmrc

sharp、canvas、bcrypt、sqlite3 这四个是原生模块重灾区。它们一编译失败，很多人会去装一整套编译工具链，其实多数情况换个 Node 版本（优先 LTS 偶数版）就能直接拿到预编译包。

装完发现还是不对，做一次干净重装：

rm -rf node_modules package-lock.json
npm install

注意是删 package-lock.json，不是删 package.json。锁文件里可能记着一个已经不存在的镜像地址，不删会一直失败。

装完自检一下有没有装漏：

npm ls --depth=0

输出里有 UNMET DEPENDENCY 就是缺包，直接 npm i 包名。

第三步：环境变量和外部服务

到这一步进程能起来，但功能一用就报错，基本是缺配置。

找 .env：

ls -a | grep env
cat .env.example

AI 项目极常见的状态：有 .env.example，没有 .env。复制一份：

cp .env.example .env

然后逐个填。空着的 DATABASE_URL、OPENAI_API_KEY、JWT_SECRET 会让服务启动时就崩，或者第一次请求才崩。

几个隐蔽的点：

1. 变量名对不上。代码读 process.env.API_KEY，.env 里写的是 APIKEY。大小写敏感，肉眼很难发现。
2. Vite / Next 的前缀规则。Vite 只有 VITE_ 开头的变量才会注入前端，Next 是 NEXT_PUBLIC_。名字对了但前缀不对，前端拿到的是 undefined。
3. 数据库没建。.env 里写了库名，但那个库根本不存在，报错是 ECONNREFUSED 或 Unknown database，看起来像连接问题，其实是库没建。
4. 第三方接口在国内不可达。前端直连 OpenAI、Supabase、Firebase 的，国内浏览器里一定超时。这类不是配置问题，得在后端加一层转发。

快速判断：该修还是该重做

三步走完，通常能定位到具体一环。但有一种情况值得直接止损：

代码里没有数据库，数据全在 localStorage 和写死的数组里。

这不是 bug，是缺了一整层。补数据层的工作量往往超过重写一个同功能的项目，而且 AI 会在补的过程中不断重写已有文件，越补越乱。

判断标准很简单，两个问题：

• 有没有一个地方统一定义了数据结构（模型 / schema / TypeScript 类型）？
• 有没有登录态和权限判断？

两个都有，值得修。两个都没有，重写更快也更便宜。

三步都过了还是不行

那就不是”跑不起来”，是”跑起来不对”。把浏览器控制台的报错截图、终端的完整日志、以及你执行过的命令一起发过来，能省掉一半沟通时间。

诊断免费，只回一句结论：能不能修、多少钱、几天。

---

相关：AI 项目接手救援 · 案例：Lovable 生成的商城，购物车一刷新就空 · 完整报价单