文档教程Vibe Coding示例工程【免费下载链接】vibe-vibeThe First Systematic Vibe Coding Open-Source Tutorial | From Zero to Full-Stack, Empowering Everyone to Build Products with AI | Live at: www.vibevibe.cn 首个系统化 Vibe Coding 开源教程 | 零基础到全栈实战让人人都能用 AI 开发产品 | 在线地址www.vibevibe.cn项目地址https://gitcode.com/datawhalechina/vibe-vibe点击查看免费下载本篇文章是 vibe-vibe 开源教程「进阶篇 · 第2章 AI 调教」中2.5 高效调试心法的完整展开。它回答一个每个 Vibe Coder 都会遇到的痛点项目报错了该怎么把问题描述给 AI才能让它一次定位、快速修复读完本文你将掌握一套可复用的 AI 调试沟通公式完整日志 操作步骤 预期结果、循环修复模式、以及「让 AI 自己 Build」的终极大招并学会用「常见错误模式速查表」快速判断错误类型、配合 vibe-vibe 仓库中的真实源码如 demo-01-todo理解错误在链路中的真实位置。一、先建立三个前置概念在进入调试方法之前先统一三个术语它们是看懂错误日志的基础调试Debug发现并修复代码错误的过程。在 Vibe Coding 语境下调试不再是纯人工排查而是「把错误信息组织好、交给 AI 分析、按反馈迭代」的人机协作过程。错误日志Error Log程序崩溃或异常时输出的详细信息包含错误类型、位置、堆栈等。日志的完整度直接决定 AI 能否一次定位问题。堆栈Stack Trace错误发生时的函数调用链显示错误是从哪一行代码、哪个函数、经过哪几层调用产生的。它能帮你以及 AI追溯错误的源头——哪怕堆栈有几十行也不要裁掉它。这三个概念背后有一个朴素的类比调试是医生诊断的过程。医生需要看到完整的症状才能准确诊断只报一句「我生病了」的模糊描述医生只能靠猜往往要反复试错很多次。二、调试沟通公式完整日志 操作步骤 预期结果为什么「报错了帮我看看」是低效的场景你运行项目时报错不知道该怎么办。❌ 低效做法——只复制最后一行错误信息发给 AI报错了帮我看看结果就是AI 反问你什么报错怎么操作的——来回 3 轮才进入正题。每一轮往返都是在消耗你的注意力也消耗 Token详见 2.1 AI 编程的经济学上下文越大、往返越多成本越高。✅ 高效做法——一次性给全信息我运行 pnpm dev 启动项目终端报错 [完整错误日志] 我预期的结果是开发服务器正常启动能在 localhost:3000 访问 帮我分析并修复这个问题注意这段提示词的三个要素它们恰好对应调试公式的三项你给的信息AI 能做的节省的轮数只说「报错了」追问细节2 轮给最后一行猜测上下文1 轮给完整日志直接定位问题0 轮把三项合起来就是本节的调试公式完整错误日志 操作步骤你做了什么 预期结果你想要什么 快速解决方案完整错误日志不要删减堆栈信息非常重要操作步骤说明你做了什么才触发错误比如我运行了pnpm dev预期结果告诉 AI 你想要的最终状态比如开发服务器能在 localhost:3000 正常访问。从公式到模板两条可直接复制的话术首次提问模板我运行 [启动/构建命令] 时终端报错 [完整错误日志] 我预期的结果是[预期行为] 请帮我分析并修复这个问题补充信息模板当需要提供更多上下文时数据库连接错误 错误: connect ECONNREFUSED 127.0.0.1:5432 环境 - 开发环境 - PostgreSQL 应该在本地运行 - .env 中 DATABASE_URLpostgresql://localhost:5432/mydb 可能的原因 1. PostgreSQL 没有启动 2. 端口不对 3. .env 配置错误值得注意的是vibe-vibe 教程的基础篇也给出了几乎相同的「通用提问骨架」见 附录 B常见错误与问 AI流程我现在遇到的问题是______ 现象______ 我刚刚做了什么______ 我原本期望发生什么______ 如果有报错这是完整报错 ______ 请先帮我判断最可能的原因再告诉我下一步只先检查什么。这说明「现象 操作 预期 完整报错」这一套沟通骨架是整个 vibe-vibe 教程从基础到进阶反复强调的通用排错原则值得内化成肌肉记忆。三、循环修复模式2-3 轮解决是常态第一轮没解决这很正常不要放弃。把 AI 给的方案执行后的新情况、新日志继续反馈回去按你的方法改了现在出现新的错误 [新错误日志] 请继续分析这套循环的流程可以画成一张图通常 2-3 轮解决。为什么迭代如此重要错误往往有连锁反应修好 A 错误可能暴露出 B 错误AI 每次修复基于的是它上一次看到的状态你如果不反馈「修复后的新日志」它就无法继续每一步「按你的方法改了现在……」都是给 AI 提供新的诊断输入让它从「猜」变成「对症下药」。这与 vibe-vibe 进阶篇 2.2 中「Trust but Verify信任但验证」的工作流理念一脉相承见 2.2 VibeCoding 工作流详解AI 生成 → 验证是否工作 → 不工作就把问题反馈回去 → 继续生成。调试只是这条闭环在「出错场景」下的具体应用。四、终极大招让 AI 自己 Build场景与操作报错一堆比如构建失败、错误信息 50 行你不想逐个排查、也不知道从哪开始直接把构建任务甩给 AI请帮我运行 pnpm install pnpm build如果遇到错误请自行修复直到构建成功然后去喝杯咖啡。为什么有效AI 直接看到真实错误它自己运行命令、自己读完整输出不依赖你的转述转述本身就会丢失信息小问题 AI 能独立解决版本冲突、缺失依赖这类问题AI 完全可以自己处理你只需要看结果把「过程」交给 AI把「验收」留给自己。适用场景场景为什么适合接手新项目不知道项目结构让 AI 自己探索报错太多逐个排查太慢让 AI 并行处理CI/CD 挂了本地复现不了让 AI 在本地跑注意事项✅先git commit保存现场AI 改坏了能随时回滚。这是 vibe-vibe 教程反复强调的安全底线——进阶篇序言中明确要求每次完成独立功能或修好一个 Bug 并验证后自动运行 git commit 提交代码见 第2章序言✅第一次可能慢耐心等待AI 要自己探索、试错、验证比直接回答慢是正常的⚠️AI 陷入死循环来回改同一处→ 及时打断如果看到它在同一个位置反复改来改去立刻用 CtrlC 之类的标准中断方式打断它重新描述问题、收敛范围。终极大招公式git commit 保存现场 让 AI 自己运行 build 遇到错误让它自己修 省心省力五、三个实战案例拆解案例 1类型错误错误日志Type error: user is possibly undefined. at App (app/page.tsx:15:10)❌ 错误描述类型错误了帮我看看—— AI 拿不到任何定位信息只能从头问起。✅ 正确描述把文件、行号、报错原文、出错代码一并给出TypeScript 报错 文件: app/page.tsx 行号: 15 错误: user is possibly undefined 代码: const user await getUser(); return div{user.name}/div; // line 15 如何处理可能为 undefined 的情况AI 分析方向user可能为 undefined需要 ① 添加类型检查、② 提供默认值、③ 或使用可选链。这类「possibly undefined」错误在 React TypeScript 项目中极其常见。在 vibe-vibe 仓库的演示项目里也能看到 TypeScript 严格模式下的同类约束例如 demo-01-todo 的 API 路由 中查询条件conditions数组在拼接前要先判空db.select().from(todos)在有条件时走where(and(...conditions))、无条件时直接排序查询——这种分支写法正是为了让类型安全与运行行为一致。如果你在类似代码上报错把出错的那几行代码原文而不是只贴报错一起发给 AI定位会快得多。案例 2运行时错误错误日志Error: connect ECONNREFUSED 127.0.0.1:5432 at Connection.anonymous (node_modules/pg/lib/client.js:89:17) at Socket.emit (events.js:315:13)❌ 错误描述数据库连接失败—— 方向正确但信息为零AI 只能给出泛泛的检查清单。✅ 正确描述给出错误、运行环境、配置、以及你怀疑的可能原因上面第二节的「补充信息模板」就是这个案例。AI 分析方向ECONNREFUSED表示目标端口没有服务在监听即服务未运行。检查 ① PostgreSQL 是否启动、② 端口是否正确默认 5432、③ 运行命令检查——Mac/Linux 用brew services listWindows 用sc query postgresql-x64-[version]。这类「连不上外部服务」的错误在 vibe-vibe 的数据库示例里同样会以显式报错的方式暴露出来看 demo-01-todo 的数据库入口它启动时就检查DATABASE_URL环境变量未设置直接throw new Error(DATABASE_URL 环境变量未设置)——这正是程序主动给出可读错误的典型写法。反过来如果你自己在.env里配了 Neon 的连接串demo 使用的是neondatabase/serverless见 package.json却仍然报连接错误那排查方向就应该是环境变量有没有被正确加载、连接串格式、网络是否可达——把这些背景写进提问AI 就能直接给出针对性答案。案例 3构建错误错误日志✘ [ERROR] Could not resolve ./components/Button app/page.tsx:3:24: 3 │ import { Button } from ./components/Button; ╩ ~~~~~~~~~~~~~~~~~~~~ This file does not exist.❌ 错误描述构建失败了—— AI 只能反问具体什么错。✅ 正确描述给出报错、文件位置、导入语句以及你对项目的了解如项目用 shadcn/uiButton 应该在 components/ui/button.tsx构建错误 Could not resolve ./components/Button 文件位置: app/page.tsx:3:24 import { Button } from ./components/Button; 实际情况 - 项目使用 shadcn/ui - Button 组件应该在 components/ui/button.tsx 如何修复导入路径AI 分析方向导入路径解析失败说明./components/Button这个相对路径下没有可解析的模块——需要核对组件真实位置、修正导入路径或检查组件是否已创建。这个案例在 vibe-vibe 的 demo 结构里有非常直观的对应demo 项目都把 shadcn/ui 组件放在src/components/ui/目录见 demo-01-todo 组件目录页面通过/components/ui/button之类的别名导入。如果你手写成了./components/Button而实际路径是/components/ui/button就会触发一模一样的 Could not resolve 构建错误。把项目的目录结构与导入别名约定告诉 AI能让这类路径错误的修复从猜变成确认。六、常见错误模式速查表把上面三类错误放进更大的图景绝大多数 AI 编码中遇到的错误都可以归入下面 7 类。遇到报错时先对照表格判断错误类型再按「调试公式」组织提问错误类型典型信息解决方向类型错误Type X is not assignable to type Y检查类型定义使用类型断言或修改类型空值错误Cannot read property X of undefined添加空值检查、可选链、默认值导入错误Module not found: Cant resolve X安装依赖、修正路径、检查导出网络错误ECONNREFUSED / ENOTFOUND检查服务状态、URL、网络连接端口占用Address already in use :3000关闭占用端口的进程或换端口权限错误EACCES / Permission denied检查文件权限使用 sudo 或更改权限语法错误Unexpected token / SyntaxError检查语法拼写注意括号引号匹配七、从源码看好项目如何自带调试线索「调试心法」讲的是人与 AI 的沟通技巧但好的工程实践能让错误更容易被定位。从 vibe-vibe 仓库的源码中可以提炼出四类自带调试线索的模式它们也是你在让 AI 修复问题时可以主动提供的额外上下文1. 在入口处主动校验环境变量demo-01-todo 的数据库入口 在初始化时就检查DATABASE_URL缺失直接抛出可读错误。这比启动后莫名其妙的 500要容易定位得多。2. 用 schema 校验把脏数据挡在业务逻辑之外demo-01-todo 的校验层 用 zod 定义createTodoSchematitle非空且不超过 200 字、category限定枚举、dueDate为可选字符串。对应地API 路由 用createTodoSchema.safeParse(body)做输入校验校验失败返回 400 和第一个错误信息数据库操作失败则捕获异常返回 500。这种输入校验错误 400 / 服务端异常 500的清晰分层让错误日志一眼就能判断问题出在调用方还是服务端。3. 错误边界 日志输出demo-01-todo 的全局错误边界 是 Next.js 的error.tsx它在useEffect里console.error(Page error:, error)把页面错误打到控制台同时向用户展示可读的错误信息与重试按钮。这意味着——当你在浏览器里看到出了点问题时完整堆栈其实在终端/浏览器控制台里把它复制进提问即可。4. 用自动化测试固化预期结果调试公式里的预期结果最好能落到测试里。demo-01-todo 的 API 测试 用 Vitest 覆盖了 GET 列表、分类过滤、POST 创建成功、空标题返回 400、缺字段返回 400 等场景运行命令见 package.json 中的pnpm test。当 AI 修复完一个 Bug你可以让它运行pnpm test确认通过——测试就是可重复验证的预期结果比口头描述可靠得多。这些源码证据想说明的是错误日志 操作步骤 预期结果这套公式不仅适用于报错了问 AI也应当贯穿到你的工程习惯里——好的错误信息、输入校验、错误边界和测试本身就是给未来的 AI和你自己留下的调试线索。八、核心理念像医生一样诊断像闭环一样迭代把全文浓缩成一张图记住五条心法完整日志不要删减堆栈信息很重要操作步骤说明你做了什么才触发错误预期结果告诉 AI 你想要什么循环修复不要放弃通常 2-3 轮解决反馈结果每次修复后告诉 AI 新情况。配套两条公式调试公式 完整错误日志 操作步骤你做了什么 预期结果你想要什么 快速解决方案 终极大招公式 git commit 保存现场 让 AI 自己运行 build 遇到错误让它自己修 省心省力最后补充一条基础篇也在强调的排错原则见 附录 B一次只改一个变量。不要一看到问题就同时改模型、改提示词、改布局、改接口、改环境变量——先判断更像哪一层的问题从那一层开始查你才知道到底是哪一步真的起了作用。这也是让 AI 的循环修复不陷入混乱的前提。相关内容前置2.2 VibeCoding 工作流详解Explore → Plan → Execute → Verify → Submit 五步流程与权限模式前置2.1 AI 编程的经济学为什么精准上下文能省钱基础篇常见错误与问 AI流程通用提问骨架 五类高频问题排查方向源码参考demo-01-todo API 测试、demo-01-todo 校验层、demo-01-todo 错误边界赞分享文档教程Vibe Coding示例工程【免费下载链接】vibe-vibeThe First Systematic Vibe Coding Open-Source Tutorial | From Zero to Full-Stack, Empowering Everyone to Build Products with AI | Live at: www.vibevibe.cn 首个系统化 Vibe Coding 开源教程 | 零基础到全栈实战让人人都能用 AI 开发产品 | 在线地址www.vibevibe.cn项目地址https://gitcode.com/datawhalechina/vibe-vibe点击查看免费下载相关推荐Vibe Coding 高效调试心法用「完整日志 循环修复」把 Bug 交给 AI一次说清问题Vibe Coding 高效调试心法用「完整日志 循环修复」把 Bug 交给 AI一次说清问题 本篇技术指南来自 vibe vibe 开源教程的「AI文档教程Vibe Coding示例工程终极忙碌模拟器用genact让终端假装工作的艺术终极忙碌模拟器用genact让终端假装工作的艺术 在技术世界中有时候看起来忙碌和真正忙碌同样重要。想象一下这样的场景你需要向同事展示复杂的系统调试CLIViolentmonkey终极指南用浏览器脚本定制你的网络世界Violentmonkey终极指南用浏览器脚本定制你的网络世界 你是否曾想过为什么每次浏览网页都要忍受那些烦人的广告弹窗为什么视频网站总是限制你的播放体验前端插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考