这一章的重点，是让你知道项目跑不起来时，第一句应该怎么问 AI。
很多小白第一次接手开源项目时，最怕的不是不会改，而是不知道怎么把项目先跑起来。
学完这一章，你应该能做到：
- 让 AI 编程助手先帮你判断项目为什么启动不了；
- 让 AI 编程助手先检查环境、依赖和启动命令；
- 让 AI 编程助手把启动问题拆成可检查的小步骤；
- 遇到报错时，不再只会贴一长串错误信息。
如果还没有打开可用的 AI 编程工具，先按第一章从官网安装并完成第一个练习，再继续这一章。
本章可直接复制的提示词
你要做的事：项目下载下来后，不知道怎么启动。
【可直接复制给 AI】
我是编程小白。这个项目我下载下来了，但不知道怎么启动。
请直接告诉我：
1. 我第一步应该运行什么命令；
2. 如果缺依赖，应该运行什么命令；
3. 如果报错，我应该复制哪一段给你；
4. 看到什么算启动成功。
【说明】
- AI 会给你安装依赖命令；
- 给你启动命令；
- 告诉你成功时浏览器应该打开哪个地址。
不满意继续这样问：
不要解释太多。
请只给我三条命令，并告诉我每条命令成功时会看到什么。
6.1 项目跑不起来，第一句复制这段
项目下载下来但跑不起来时，不要先乱删文件，也不要先乱换命令。先复制这段给 AI：
我是编程小白。这个项目下载下来了，但是跑不起来。
请直接告诉我：
1. 应该先检查哪个文件；
2. 应该用 npm、pnpm、yarn 还是别的命令；
3. 安装依赖应该运行什么；
4. 启动项目应该运行什么；
5. 如果报错，我应该复制哪一段给你；
6. 看到什么算启动成功。
请直接告诉我下一步动作。
【说明】AI 会先帮你确认启动命令，而不是让你盲目试。
比如你看到别人分享了一个热门项目：
一个 AI Chatbot 模板
一个 shadcn 落地页模板
一个 vibe coding app builder
一个开源后台管理系统
一个 Next.js + Supabase 项目
你兴冲冲 clone 到本地，结果第一步就卡住：
npm install
报错。
换成：
pnpm install
还是报错。
再运行：
npm run dev
终端一片红。
很多人这时候会开始乱试：
删 node_modules
删 lock 文件
换 npm
换 pnpm
升级 Node
降级 Node
复制别人命令
问群友
重启电脑
有时候能碰巧解决，有时候越修越乱。
如果你已经有报错，继续这样问：
这是我运行命令后的完整报错：
（粘贴报错）
请只找第一条真正的错误原因。
不要一次给我很多方案。
请告诉我下一步只需要运行哪一条命令，或者打开哪个文件确认。
这样问的好处是：AI 会围绕“下一步动作”回答，而不是展开一大堆项目介绍。
本章会用几个真实类型的热门项目做案例：
AI Chatbot 模板
shadcn 落地页模板
vibe coding app builder
Open Lovable 类 AI 生成项目
老旧 Next.js 项目
重点不是背命令，而是学会让 AI 编程工具帮你判断：
这个项目应该用什么包管理器？
需要什么 Node 版本？
缺哪些环境变量？
启动命令到底是哪一个？
第一条真正的报错是什么？
有没有必要改代码？
6.2 先做一个“项目启动体检 Skill”
如果每次启动项目都重新写一长串提示词，很累。
更好的办法是做一个简单的 Skill。
你可以把它叫做：
project-startup-doctor
中文名字可以叫：
项目启动体检 Skill
它不是网上随便找的第三方工具，也不需要你安装乱七八糟的东西。
它就是一个写给 AI 编程工具的固定检查流程。
这个 Skill 的目标很简单：
每次启动新项目之前，先让 AI 编程工具按同一套清单检查。
这个 Skill 适合做什么
适合：
clone 新项目后第一次启动
接手旧项目
模板项目跑不起来
AI 生成的项目跑不起来
项目 README 写得不清楚
不知道用 npm、pnpm 还是 yarn
不知道缺什么环境变量
不知道 Node 版本对不对
不适合：
直接修业务 bug
大规模重构
修改页面样式
改数据库结构
改支付逻辑
改生产配置
启动体检只做一件事：
先判断项目如何安全跑起来。
Skill 内容示例
你可以在项目或个人 skills 目录里创建一个 SKILL.md，内容可以这样写：
# 项目启动体检 Skill
当用户要启动一个陌生项目、clone 的开源项目、模板项目或 vibe coding 生成项目时，先执行本 Skill。
## 目标
在修改任何代码之前，先判断项目如何安全启动。
## 工作流程
1. 先读取项目根目录，不要修改文件。
2. 检查是否存在 package.json、README.md、lock 文件、.env.example、.nvmrc。
3. 判断包管理器：npm、pnpm、yarn、bun。
4. 判断 Node 版本要求。
5. 读取 package.json 的 scripts 字段，找出 install、dev、build、test、lint 命令。
6. 检查 README 里的启动说明是否和 package.json 一致。
7. 检查是否缺少环境变量。
8. 如果用户提供报错日志，先找第一条真正的根因错误。
9. 输出排查结论，不要直接修改代码。
10. 只有用户确认后，才允许给出最小修改方案。
## 输出格式
请固定按以下格式输出：
- 项目类型：
- 包管理器：
- Node 版本要求：
- 安装命令：
- 启动命令：
- 构建命令：
- 是否需要环境变量：
- 当前最可能的启动失败原因：
- 下一步建议：
- 暂时不要做的事：
## 禁止事项
- 不要一上来删除 node_modules。
- 不要一上来删除 lock 文件。
- 不要编造环境变量。
- 不要修改 package.json。
- 不要新增依赖。
- 不要改业务代码。
不想做 Skill，也可以直接复制这段提示词
请作为“项目启动体检助手”帮我检查当前项目。
要求：
1. 先不要修改任何文件
2. 先读取当前文件夹、README、package.json、lock 文件和环境变量示例
3. 判断包管理器、Node 版本、启动命令、构建命令
4. 如果我提供报错日志，请先找第一条真正的根因错误
5. 不要一上来删除 node_modules 或 lock 文件
6. 不要编造环境变量
7. 最后给出启动排查顺序
请按这个格式输出：
- 项目类型：
- 包管理器：
- Node 版本要求：
- 安装命令：
- 启动命令：
- 构建命令：
- 是否需要环境变量：
- 当前最可能的启动失败原因：
- 下一步建议：
- 暂时不要做的事：
6.3 案例一：AI Chatbot 模板 clone 下来跑不起来
第一个案例，我们用一个很常见的项目类型：
Next.js + AI SDK + Chatbot 模板
这类项目现在很热门。
很多人想做：
AI 聊天机器人
私有知识库问答
API 中转演示页面
多模型聊天工具
企业内部 AI 助手
客服机器人
于是 clone 一个开源 AI Chatbot 模板回来。
结果一跑，问题来了。
你可能遇到的情况
你运行：
npm install
npm run dev
然后可能看到：
缺少 OPENAI_API_KEY
缺少 AUTH_SECRET
缺少 DATABASE_URL
缺少 POSTGRES_URL
模块找不到
Node 版本不匹配
pnpm lock 文件存在，但你用了 npm
这类项目不是简单静态页面。
它通常可能涉及：
AI 模型 API Key
数据库
登录认证
流式输出
服务端 API Route
环境变量
部署平台配置
所以不要一上来让 AI 编程工具直接修。
推荐提示词
我 clone 了一个 AI Chatbot 模板项目，现在本地跑不起来。
请先分析当前项目，不要修改任何文件。
请你先做启动体检：
1. 阅读 package.json，判断项目框架和包管理器
2. 阅读 README，找出官方启动步骤
3. 检查是否有 .env.example 或类似文件
4. 汇总项目需要哪些环境变量
5. 判断哪些环境变量必须我自己填写
6. 判断当前报错是依赖问题、环境变量问题，还是数据库问题
7. 给出最安全的启动顺序
注意：
- 不要编造 API Key
- 不要修改 .env
- 不要删除 lock 文件
- 不要改业务代码
AI 编程工具应该重点检查哪些文件
这类项目通常要看：
package.json
README.md
.env.example
app/api/chat/route.ts
lib/ai/*
lib/db/*
drizzle.config.ts
next.config.js
如果项目使用 Supabase，可能要看：
supabase/
middleware.ts
lib/supabase/*
.env.example
如果使用 NextAuth / Auth.js，可能要看：
auth.ts
middleware.ts
app/api/auth/*
让 AI 编程工具生成环境变量清单
请根据当前项目中实际使用的环境变量，生成一份“本地启动所需环境变量清单”。
要求：
1. 只列变量名，不写真实值
2. 标明每个变量大概用途
3. 标明是否必须
4. 标明能不能用占位值
5. 不要编造不存在的变量
输出可以是：
新手最容易错在哪里
最容易错的是把 .env.example 复制成 .env 后，里面还是空值。
比如：
OPENAI_API_KEY=
DATABASE_URL=
AUTH_SECRET=
这不叫配置好了。
你要让 AI 编程工具判断：
这些变量哪些必须填真实值，哪些本地可以先用占位值？
修复顺序
推荐让 AI 编程工具给出这种顺序：
1. 确认包管理器
2. 确认 Node 版本
3. 安装依赖
4. 复制 .env.example
5. 填必要环境变量
6. 如果需要数据库，先启动数据库
7. 运行迁移或初始化命令
8. 再运行 dev
不要跳过环境变量和数据库直接跑。
6.4 案例二：shadcn 落地页模板，为什么 npm run dev 失败
第二个案例，用一个更适合新手的热门项目类型：
shadcn + React + Tailwind + Landing Page 模板
这种项目适合拿来做：
SaaS 官网
AI 工具落地页
API 服务官网
课程销售页
产品介绍页
个人项目主页
它比 AI Chatbot 简单，因为通常不需要数据库，也不一定需要后端。
但它仍然可能跑不起来。
你可能遇到的问题
常见问题包括：
Node 版本不对
包管理器用错
Tailwind 版本不兼容
Vite 启动端口被占用
路径别名 @ 配置错
组件缺失
shadcn 组件没有正确复制
这类项目很适合练习 AI 编程工具启动排查。
推荐提示词
我 clone 了一个 shadcn 落地页模板，现在 npm run dev 失败。
请先分析当前项目，不要修改任何文件。
请你帮我做启动体检：
1. 判断这是 Vite、Next.js 还是其他框架
2. 判断应该用 npm、pnpm、yarn 还是 bun
3. 检查 package.json 的 scripts
4. 检查是否有路径别名配置
5. 检查 Tailwind / shadcn 相关配置文件
6. 根据错误日志找第一条根因错误
7. 给出最小修复方案
限制：
- 不要重写页面
- 不要升级所有依赖
- 不要删除 lock 文件
- 不要新增 UI 库
AI 编程工具应该看哪些文件
如果是 Vite + React：
package.json
vite.config.ts
tsconfig.json
tailwind.config.ts
components.json
src/main.tsx
src/App.tsx
如果是 Next.js：
package.json
next.config.js
tsconfig.json
tailwind.config.ts
components.json
app/page.tsx
components/*
常见报错：路径别名找不到
你可能看到：
Cannot find module '@/components/ui/button'
这时候不要直接新建 button 文件。
先问 AI 编程工具：
报错显示找不到 @/components/ui/button。
请先判断：
1. 这是组件文件缺失，还是路径别名配置问题
2. 应该检查 tsconfig.json 还是 vite.config.ts
3. components.json 是否和当前文件清单一致
4. 是否需要重新添加 shadcn button 组件
5. 不要直接创建文件，先给排查步骤
常见报错：Tailwind 样式没生效
如果页面能打开，但样式全乱：
按钮没样式
布局全挤在一起
颜色不对
字体不对
className 没效果
提示词可以这样写：
页面能启动，但 Tailwind 样式没有生效。
请先分析当前项目，不要修改文件。
请帮我检查：
1. Tailwind 配置文件是否存在
2. CSS 入口文件是否正确引入
3. content 路径是否覆盖当前组件目录
4. PostCSS 配置是否存在
5. 这是配置问题还是组件问题
请给出最小修复方案。
这个案例适合怎么练
你可以让 AI 编程工具做三轮：
第一轮，只读：
先读取当前文件夹，不要修改。
第二轮，定位：
根据报错找第一条根因。
第三轮，最小修改：
只允许修改配置文件，不要改页面代码。
这样练习很适合新手。
6.5 案例三：vibe coding 生成的项目，为什么更要先体检
现在很多人会用 vibe coding 工具生成项目。
你可能用自然语言生成了一个：
记账工具
待办事项应用
AI 图片生成页面
API 价格计算器
个人作品集
SaaS 落地页
后台管理面板
生成的时候看起来很厉害。
但导出到本地后，经常会发现：
依赖很乱
组件很多
文件命名不统一
环境变量没写清楚
README 很简单
没有测试
构建失败
页面能跑但逻辑不完整
这时候不要急着继续让 AI 加功能。
先让 AI 编程工具体检。
推荐提示词
这是一个 vibe coding 工具生成的项目。
我想先确认它能不能安全地在本地运行。
请先分析当前项目，不要修改任何文件。
请你帮我检查：
1. 项目技术栈
2. 包管理器
3. 启动命令
4. 构建命令
5. 是否缺少 README
6. 是否缺少环境变量说明
7. 是否有明显的依赖风险
8. 是否有明显的目录混乱
9. 新手第一步应该先修什么
注意：
- 不要直接重构
- 不要新增功能
- 不要优化 UI
- 先只做启动体检
vibe coding 项目最容易出现的问题
第一类：依赖堆太多。
装了很多 UI 库
装了重复功能的包
装了没用到的依赖
版本不兼容
第二类：文件结构像是拼出来的。
components 里什么都有
lib 里既有 API 又有工具函数
页面逻辑和数据混在一起
第三类：README 不够用。
没有安装说明
没有环境变量说明
没有构建说明
没有部署说明
第四类：能启动但不能构建。
dev 模式没事
build 一跑就挂
所以你要让 AI 编程工具先做“能不能上线”的判断，而不是只看“能不能打开页面”。
让 AI 编程工具给出项目健康分
你可以这样问：
请给这个项目做一个启动健康评分。
评分维度：
1. 依赖清晰度
2. 启动命令清晰度
3. 环境变量清晰度
4. 构建稳定性
5. 文件清单清晰度
6. 新手接手难度
每项 1-5 分。
请说明扣分原因。
不要修改文件。
这个评分很好用。
它能让你知道这个 vibe coding 项目是：
可以继续改
需要先整理
不适合继续投入
6.6 案例四：Open Lovable 类项目，依赖能装但启动流程复杂
Open Lovable 这类项目很有代表性。
它不是简单页面模板，而是一个 AI 生成应用的工具型项目。
这类项目通常会涉及：
前端页面
API 调用
LLM Provider
抓取或解析网页
运行时配置
环境变量
本地开发服务
所以它不是“npm run dev”这么简单。
你可能遇到的问题
比如：
依赖装好了，但页面空白
运行后提示缺 API Key
某个 provider 没配置
服务端接口 500
浏览器控制台报 CORS
终端说某个变量 undefined
这类项目要先分清楚：
是前端启动失败？
还是后端接口失败？
还是模型 API 失败？
还是环境变量失败？
推荐提示词
这是一个 AI app builder / Open Lovable 类项目。
项目可以安装依赖，但启动后不能正常使用。
请先分析当前项目，不要修改文件。
请帮我分层排查：
1. 前端是否成功启动
2. API 路由是否正常
3. 是否缺少模型 API Key
4. 是否缺少抓取/解析相关配置
5. 浏览器控制台错误和终端错误分别说明什么
6. 当前问题属于前端、后端、环境变量、还是第三方 API
请先输出排查计划，不要直接修。
分层排查很重要
这类项目一出错，新手很容易把所有问题混在一起。
其实要拆成四层：
你可以让 AI 编程工具按这个表格输出：
请按四层排查法输出：
前端层：
API 层：
环境变量层：
第三方服务层：
每层说明：
- 当前证据
- 可能原因
- 下一步检查命令
- 是否需要改代码
不要让 AI 编程工具直接改 provider
这类项目经常有多个模型提供商。
不要直接让 AI 编程工具改：
OpenAI
Anthropic
Gemini
DeepSeek
OpenRouter
更稳的说法：
请先判断当前默认 provider 是哪个，以及它需要哪些环境变量。
不要切换 provider，不要改模型名，先只分析。
6.7 案例五：老项目 Node 版本太旧，AI 编程工具不要乱升级
第五个案例是旧项目。
你可能 clone 一个几年前的项目，里面写着：
Next.js 12
React 17
Webpack 4
Node 14
旧版 Tailwind
旧版 ESLint
你电脑现在可能是：
Node 20
Node 22
npm 10
于是安装直接炸。
不要一上来升级整个项目
很多新手会让 AI 编程工具：
帮我把依赖升级到最新版。
这非常危险。
旧项目升级不是小事。
可能牵扯：
Next.js 路由变化
React 版本变化
Webpack 配置变化
ESLint 规则变化
Node API 变化
Tailwind 配置变化
正确做法是先判断：
是为了本地跑起来，还是为了长期升级？
这两个目标完全不同。
推荐提示词
这是一个比较旧的项目，现在安装依赖失败。
请先分析当前项目，不要修改文件。
请帮我判断：
1. package.json 是否声明 Node 版本
2. 是否存在 .nvmrc
3. 当前依赖大概属于哪个年代
4. 最安全的方式是切换旧 Node 版本，还是升级依赖
5. 如果只是为了本地跑起来，最小操作是什么
6. 如果要长期维护，升级需要分几步
限制：
- 不要直接升级所有依赖
- 不要修改 package.json
- 不要删除 lock 文件
- 不要重构项目
两条路线
AI 编程工具应该给你两条路线：
第一条：只为了跑起来。
切换到项目要求的 Node 版本
按 lock 文件安装
尽量不升级依赖
第二条：为了长期维护。
先建新分支
逐步升级 Node
逐步升级框架
逐步修复破坏性变更
每一步都跑测试
这两条不能混在一起。
推荐让 AI 编程工具这样输出
请把方案分成两类：
A. 只为了本地跑起来
B. 为了长期升级维护
每类都写：
- 目标
- 操作步骤
- 风险
- 是否需要改代码
- 验收命令
6.8 案例六：项目能 dev，但 build 过不了
这是非常常见的坑。
很多项目：
npm run dev 可以跑
npm run build 直接挂
新手容易觉得：
能打开页面就行。
但如果 build 过不了，说明它可能无法部署。
常见原因包括：
TypeScript 类型错误
ESLint 错误
缺少环境变量
SSR 阶段访问 window
组件只适合浏览器运行
动态路由缺参数
图片配置问题
API 在构建时被调用失败
推荐提示词
项目 npm run dev 可以运行，但 npm run build 失败。
请先分析当前项目，不要修改文件。
下面是 build 日志：
{粘贴完整日志}
请你帮我：
1. 找出第一条真正导致 build 失败的错误
2. 区分根因错误和后续连锁错误
3. 判断是 TypeScript、ESLint、环境变量、SSR，还是配置问题
4. 告诉我需要查看哪些文件
5. 给出最小修复方案
6. 不要直接修改，先输出分析
常见 build 错误分类
不要让 AI 编程工具用暴力解法
错误做法：
把 TypeScript 报错都修掉，能 build 就行。
AI 编程工具可能会：
加一堆 any
关闭 ESLint
忽略类型检查
删掉出错逻辑
更好的说法是：
请给出最小且安全的修复方案，不要通过关闭类型检查、关闭 ESLint 或删除功能来解决。
6.9 本章通用模板
下面这些模板可以直接复制。
模板一：项目启动体检
请作为“项目启动体检助手”检查当前项目。
要求：
1. 先不要修改任何文件
2. 读取当前文件夹、README、package.json、lock 文件、环境变量示例
3. 判断包管理器、Node 版本、启动命令、构建命令
4. 如果我提供报错日志，请先找第一条真正的根因错误
5. 不要删除 node_modules
6. 不要删除 lock 文件
7. 不要编造环境变量
8. 最后给出启动排查顺序
输出格式：
- 项目类型：
- 包管理器：
- Node 版本要求：
- 安装命令：
- 启动命令：
- 构建命令：
- 是否需要环境变量：
- 当前最可能失败原因：
- 下一步建议：
- 暂时不要做的事：
模板二：AI Chatbot 项目启动失败
我 clone 了一个 AI Chatbot 模板项目，本地跑不起来。
请先分析当前项目，不要修改文件。
请检查：
1. 包管理器
2. Node 版本
3. README 启动步骤
4. .env.example
5. 模型 API Key 要求
6. 数据库要求
7. 登录认证配置
8. 当前报错属于哪一类
注意：
- 不要编造 API Key
- 不要改 .env
- 不要改业务代码
模板三：shadcn 模板启动失败
我 clone 了一个 shadcn 落地页模板，现在启动失败。
请先分析当前项目，不要修改文件。
请检查：
1. 框架类型
2. 包管理器
3. scripts 字段
4. Tailwind 配置
5. shadcn components.json
6. 路径别名配置
7. 第一条根因错误
限制：
- 不升级所有依赖
- 不新增 UI 库
- 不删除 lock 文件
模板四：vibe coding 项目体检
这是一个 vibe coding 工具生成的项目。
请先分析当前项目，不要修改文件。
请帮我做项目健康检查：
1. 技术栈是否清晰
2. 启动命令是否清晰
3. 环境变量是否清楚
4. 构建是否可能通过
5. 依赖是否过多
6. 目录是否混乱
7. 是否适合继续投入
请每项 1-5 分，并说明原因。
模板五：dev 能跑但 build 失败
项目 dev 可以运行，但 build 失败。
下面是 build 日志：
{粘贴完整日志}
请先分析当前项目，不要修改文件。
请帮我：
1. 找第一条根因错误
2. 区分根因和连锁错误
3. 判断错误类型
4. 给出最小修复方案
5. 不要用关闭类型检查、关闭 ESLint 或删除功能来解决
6.10 本章总结
现在写 AI 编程工具教程，不能只写：
npm install 报错怎么办
更好的方式是：
拿真实项目练启动体检。
你可以选择：
AI Chatbot 模板
shadcn 落地页模板
vibe coding 生成项目
Open Lovable 类项目
老旧 Next.js 项目
让 AI 编程工具不只是回答报错，而是按一套固定流程检查：
项目类型
包管理器
Node 版本
环境变量
启动命令
构建命令
第一条根因错误
最小修复方案
本章你要记住一句话：
跑不起来的项目，不要先修代码，先做体检。
新手最稳的工作流是：
clone 项目
先启动体检
确认包管理器
确认 Node 版本
确认环境变量
安装依赖
运行 dev
运行 build
再决定是否修改代码
下一章可以继续改成：
用 Taste Skill、shadcn landing page、Open Lovable 这类素材，让 AI 编程工具不只是“改页面”，而是按热门开源项目的结构和审美，把丑页面改成能截图、能发教程、能上线的落地页。