常见问题

开发环境问题

Node.js 版本不对

问题：运行 pnpm install 报错，提示 Node 版本不匹配。

解决：

# 查看当前版本
node -v

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装推荐版本
nvm install 20
nvm use 20

依赖安装失败

问题：pnpm install 一直卡住或报错。

解决：

# 清理缓存
pnpm store prune

# 删除 node_modules 和 lockfile
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

如果在国内，可能需要配置镜像源：

pnpm config set registry https://registry.npmmirror.com

端口被占用

问题：运行 pnpm dev 提示端口 3000 已被占用。

解决：

# 查找占用端口的进程
lsof -i :3000

# 杀掉进程
kill -9 <PID>

# 或者换个端口
pnpm dev --port 3001

AI 编程问题

AI 生成的代码跑不起来

问题：AI 写的代码有语法错误或者缺少依赖。

解决：

先看错误信息，通常会提示缺少什么
把错误信息复制给 AI，让它修复
如果是缺少依赖，运行 pnpm add <package-name>

AI 改了不该改的文件

问题：AI 把整个项目都改乱了。

解决：

# 查看改动
git diff

# 撤销所有改动
git checkout .

# 或者只撤销某个文件
git checkout <file-path>

预防：

每次让 AI 改代码前先 commit
明确告诉 AI 只改哪个文件
用 Plan 模式让 AI 先说计划

AI 一直在重复同样的错误

问题：AI 改了代码，还是报同样的错，改了又报错。

解决：

停下来，不要让 AI 继续改
自己看一下错误信息，理解问题
换一个 AI 工具或模型
把完整的错误日志和上下文一起给 AI

部署问题

部署后页面空白

问题：本地运行正常，部署后打开是空白页。

解决：

打开浏览器控制台（F12），看有没有报错
检查环境变量是否配置正确
检查构建命令是否正确
查看部署平台的日志

环境变量不生效

问题：在部署平台配置了环境变量，但代码里读不到。

解决：

确认变量名前缀是否正确（如 Cloudflare 需要 VITE_ 前缀）
重新部署（改环境变量后需要重新部署）
检查是在服务端还是客户端读取（客户端只能读取公开变量）

部署后 API 请求失败

问题：本地 API 能调通，部署后 404 或 CORS 错误。

解决：

检查 API 路径是否正确（部署后可能需要加前缀）
检查 CORS 配置
确认 API 路由是否正确部署

数据库问题

连接数据库失败

问题：代码报错说连不上数据库。

解决：

检查数据库连接字符串是否正确
确认数据库服务是否启动
检查网络是否能访问数据库（防火墙、IP 白名单）
确认用户名密码是否正确

数据库迁移失败

问题：运行 migration 报错。

解决：

# 查看当前迁移状态
pnpm db:status

# 回滚上一次迁移
pnpm db:rollback

# 重新运行迁移
pnpm db:migrate

性能问题

页面加载很慢

问题：打开页面要等很久。

解决：

打开浏览器 Network 面板，看哪个请求慢
如果是图片慢，压缩图片或用 CDN
如果是 JS 慢，检查是否引入了不必要的库
如果是 API 慢，优化后端查询

构建时间太长

问题：每次 pnpm build 要等很久。

解决：

检查是否有不必要的依赖
使用增量构建
考虑换更快的构建工具（如 Vite）

其他问题

Git 冲突不会解决

问题：拉代码时提示有冲突。

解决：

# 查看冲突文件
git status

# 打开冲突文件，手动选择保留哪部分
# 搜索 <<<<<<< 标记

# 解决后标记为已解决
git add <file>

# 完成合并
git commit

不知道该用什么技术栈

问题：看了很多教程，还是不知道该选什么。

解决：

如果是内容站，用 Astro
如果是 SaaS 产品，用 React Router + Hono
如果已有 Next.js 项目，继续用 Next.js
不要纠结，先选一个开始

详见技术栈选择指南。

遇到看不懂的错误

问题：报错信息完全看不懂。

解决：

把完整的错误信息复制到 Google 搜索
把错误信息发给 AI，让它解释
在相关项目的 GitHub Issues 里搜索
在 Stack Overflow 搜索

还是解决不了？

如果以上方法都试过了还是不行：

把问题描述清楚（包括错误信息、环境、复现步骤）
在项目的 GitHub Issues 提问
在相关社区求助（Discord、论坛）
考虑换一个方案

记住：卡住超过 2 小时，就该换个方向了。不要在一个问题上死磕。

目录