Vibe Coder 手册

1.1什么是 Vibe Coding

Vibe Coding（氛围编程）指的是一种以自然语言描述需求、由 AI 生成代码的开发方式。你告诉 AI"帮我做一个能记录待办事项的网页"，AI 就写出几十上百行代码；你再说"加一个删除按钮"，它继续修改。整个过程中，你更像产品经理和验收员，而不是传统意义上的程序员。

这种方式极大地降低了创造软件的门槛：不会语法也能做出能跑的应用。但它带来一个新的问题——当代码报错、接口连不上、数据库查不出数据时，如果你完全看不懂 AI 在写什么，就会陷入"改一句、坏三处"的循环。

1.2为什么"能跑"还不够

AI 生成代码的速度，往往超过你理解代码的速度。短期看这很爽，长期看有三个隐患：

出错时无法自救。报错信息里全是术语——端口占用、CORS、外键约束——看不懂就只能反复把报错丢回给 AI，碰运气式修复。

无法判断 AI 的答案对不对。AI 可能写出有安全漏洞的代码（比如把密码明文存进数据库），看不懂概念就识别不了风险。

需求描述不到位。懂概念的人会说"给 users 表的 email 字段加唯一索引"，不懂的人只能说"邮箱别重复注册"——前者得到的代码质量明显更好。

1.3本手册的使用方法

每个概念统一按五个维度讲解，方便快速查阅：一句话定义、生活类比、实例演示、常见坑、AI 提示词。

建议第一遍通读第一、二章建立全景认知，其余章节按需查阅：AI 生成的项目里出现了什么，就翻对应章节。

1.4一张概念地图

一个典型的 AI 生成 Web 应用，几乎必然涉及以下层次。本手册的章节顺序与此对应：

2.1编程语言：给计算机看的"菜谱"

一句话定义：编程语言是一套人与计算机约定的语法，用来精确描述"一步步该做什么"。

生活类比：菜谱。自然语言的菜谱写"盐适量"，人看得懂，计算机却会崩溃——它要求每一步都精确无歧义。编程语言就是没有歧义的菜谱语言。

编译与解释：有的语言需要先"翻译"成机器码再运行（编译型，如 Java、Go），改代码要重新构建（build）；有的边翻译边执行（解释型，如 Python、JavaScript），通常保存即生效。

2.2前端、后端与全栈

一句话定义：前端是用户看得见、摸得着的界面部分；后端是躲在服务器上处理数据和逻辑的部分。

生活类比：餐厅。前端是装修、菜单和服务员——你直接打交道的部分；后端是后厨——你点完菜，真正切菜、开火、装盘的地方。

一个人（或一个 AI）同时写前端和后端，就叫全栈开发。Vibe Coding 项目大多是全栈项目，所以你两侧的概念都会遇到。

2.3客户端与服务器

一句话定义：客户端是发起请求的一方（你的浏览器/App），服务器是接收请求并返回结果的一方（远端那台 7×24 小时开机的电脑）。

你在浏览器输入网址，浏览器（客户端）把请求发给服务器；服务器查数据库、跑逻辑，把网页或数据送回来。这个"请求—响应"的一来一回，是第四章 HTTP 的全部基础。

2.4框架与库：站在别人的肩膀上

一句话定义：库（Library）是你拿来调用的现成工具集；框架（Framework）是一套搭好的骨架，你把代码填进它规定的位置。

生活类比：做饭。库像调料和半成品——想用就用；框架像火锅店的整套流程——锅底、配菜顺序、上菜节奏都已定好，你只负责往里下菜。

常见：前端框架 React、Vue；后端框架 Express（Node.js）、Django/Flask（Python）。AI 生成的项目几乎总是基于某个框架——项目根目录的 package.json 或 requirements.txt 里会写明。

2.5运行时与环境

运行时（Runtime）：让代码跑起来的执行环境。JavaScript 原本只能在浏览器里跑，Node.js 让它也能在服务器上跑——所以你会看到"后端用 Node.js"这种说法。

开发环境与生产环境：开发环境是你自己电脑上"边改边试"的版本（常叫 dev 或 local）；生产环境是部署上线、给真实用户用的版本（常叫 prod）。两者的数据库、域名、密钥通常完全不同。AI 经常默认帮你连开发环境——上线前务必确认配置切换正确。

3.1JSON 是什么

一句话定义：JSON（JavaScript Object Notation）是一种用纯文本表示结构化数据的格式，是当今互联网上传输数据的事实标准。

生活类比：标准快递面单。不管寄什么，面单的栏目格式统一，任何分拣中心都能看懂。JSON 就是程序之间的"标准面单"——前端、后端、数据库、第三方服务，全都认它。

你在 Vibe Coding 中会在三个地方密集遇到 JSON：API 请求和返回数据、配置文件（如 package.json）、以及让 AI 生成结构化内容时的输出格式。

3.2六种数据类型

3.3六条铁律：为什么 AI 生成的 JSON 也会报错

3.4实例：一个嵌套的订单数据

{
  "orderId": "A20250727001",
  "user": {
    "name": "张三",
    "vip": true
  },
  "items": [
    { "sku": "B-101", "title": "机械键盘", "price": 399 },
    { "sku": "M-205", "title": "无线鼠标", "price": 99 }
  ],
  "coupon": null,
  "total": 498
}

读法：最外层是一个对象；user 是嵌套对象；items 是数组，里面装了两个对象；coupon 是空值。取"第一个商品的价格"，路径就是 items[0].price——这个"点+下标"的取值路径写法在大多数语言里通用。

3.5JSON 与其他常见格式

3.6Vibe Coding 场景速查

4.1HTTP：一问一答的通信规则

一句话定义：HTTP 是客户端与服务器之间传输数据的协议，规定了"请求怎么写、响应怎么回"的格式。

生活类比：写信。你按格式写好信封（地址、邮编）和信纸（正文），邮局才收；对方回信也同样按格式来。HTTP 里，信封叫请求头（Header），信纸叫请求体（Body）。

一次 HTTP 通信包含四个要素：URL（地址）、Method（方法，要干什么）、Header（元信息，如身份凭证）、Body（真正要传的数据，通常就是 JSON）。

4.2四种常用方法：对应增删改查

这四个方法恰好对应数据库的增删改查（CRUD），是连接第四章和第五章的桥梁。

4.3状态码：服务器回复的"表情"

每次响应都有一个三位数字的状态码。看到报错先找状态码，问题就定位了一半：

4.4API：程序的"服务窗口"

一句话定义：API（应用程序接口）是程序对外提供功能的标准入口——你按约定发请求，它按约定返回结果，不用关心内部实现。

生活类比：银行柜台。你不需要知道金库在哪里、账目怎么记，只需填对单子递进去，柜员按流程给你结果。API 文档就是"填单说明"。

REST API：目前最流行的 API 设计风格，核心思想是"URL 表示资源，方法表示动作"。例如 GET /users/42 表示"读取 42 号用户"，DELETE /users/42 表示"删除 42 号用户"——看 URL 和方法就能猜到功能。

4.5API Key 与鉴权

大多数 API 不会随便让人调用，需要你提供凭证：

4.6实例：读懂一段 API 调用代码

AI 生成的项目里，前端调用后端接口通常长这样（JavaScript）：

const res = await fetch("https://api.example.com/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + token
  },
  body: JSON.stringify({ item: "B-101", qty: 1 })
});
const data = await res.json();  // 把响应解析成 JSON 对象

逐行对照：method 是 POST；headers 里既有内容类型又有身份凭证；body 是把 JSON 对象转成字符串再发送；最后一行对应第三章——服务器返回的是 JSON 文本，要解析后才能用。以后看到 fetch 或 axios 开头的代码块，都知道它在干什么了。

5.1数据库是什么

一句话定义：数据库是有结构地持久存储数据、并支持高效查询的系统；MySQL 是其中最流行的开源关系型数据库之一。

生活类比：Excel 的工业加强版。一张表就像一张 Excel 表，但数据库能同时服务成千上万人的读写、保证数据不乱、支持毫秒级从百万行里找到你要的那一行。

5.2表、行、列：数据库的语法单位

关系型数据库的世界只有三个名词：表（Table）是一类事物的集合；列（Column）是这类事物的属性；行（Row）是一个具体的事物。

5.3SQL：和数据库对话的语言

一句话定义：SQL 是查询和操作数据库的标准语言。你写一句 SELECT，数据库执行后把结果返回给你。最常用的四句对应增删改查（CRUD）：

-- 查：找出 vip 为 true 的用户，按注册时间倒序，取前 10 个
SELECT * FROM users WHERE vip = 1 ORDER BY created_at DESC LIMIT 10;

-- 增：插入一个新用户
INSERT INTO users (name, email) VALUES ("赵六", "zhaoliu@example.com");

-- 改：把 2 号用户的名字改掉
UPDATE users SET name = "李四(已改名)" WHERE id = 2;

-- 删：删除 3 号用户
DELETE FROM users WHERE id = 3;

5.4主键、索引与多表关联

主键（Primary Key）：每行数据的唯一编号，通常是自增的 id。有了它，"第 42 号订单"这种说法才有意义。

索引（Index）：类比书的目录。没有索引，按 email 查用户要一行行翻完全表（全表扫描）；给 email 建了索引，就像翻目录直达页码。数据量大后，慢查询十有八九是缺索引——直接告诉 AI"给这个查询字段加索引"即可。

关联（JOIN）：订单表只存 user_id 而不是用户全名，查询时通过 JOIN 把两张表拼起来。这就是"关系型"的含义——表与表通过 id 建立关系，避免同一份信息重复存储。

5.5连接数据库：看懂连接配置

程序连数据库需要五样信息，它们通常出现在 .env 文件中：

报错 Connection refused 多半是数据库没启动或端口不对；报错 Access denied 多半是账号密码错。

5.6MySQL 和它的兄弟们

6.1为什么需要版本控制

一句话定义：Git 是记录代码每一次修改历史的工具，可以随时查看、对比、回退到任何一个历史版本。

生活类比：游戏的存档系统。每过一关存个档，后面打砸了随时读档重来；还能开多个平行存档尝试不同打法，打得好再合并回主线。

Vibe Coding 尤其需要 Git：AI 一次大改可能动几十个文件，改得好提交存档，改崩了一键回退——没有 Git，一次失败的 AI 修改就可能毁掉整个项目。

6.2五个核心概念

6.3最常用的八条命令

# 在当前文件夹初始化仓库
git init

# 看看哪些文件被改动了
git status

# 把所有改动放入"待提交区"
git add .

# 存档，写一句本次改了什么
git commit -m "说明"

# 查看历史存档列表
git log --oneline

# 新建并切换到 feature 分支
git checkout -b feature

# 把 feature 分支合并进当前分支
git merge feature

# 把本地存档推送到 GitHub 备份
git push

日常 90% 的场景就是 add → commit → push 三连。每次让 AI 做完一个可运行的小功能，就提交一次——这是 Vibe Coding 最重要的习惯。

6.4GitHub：代码的云盘 + 社交网

Git 是工具，GitHub 是基于 Git 的在线托管平台（类似的还有 Gitee、GitLab）。把仓库 push 到 GitHub 有三重价值：异地备份不怕电脑坏；随时随地继续开发；大多数一键部署平台都直接对接 GitHub 仓库，push 代码即自动上线。

6.5.gitignore：告诉 Git"这些别管"

一句话定义：.gitignore 是一个清单文件，列在其中的文件/文件夹 Git 一律不追踪、不上传。三类东西必须进 .gitignore：

1. .env——里面是数据库密码和 API Key，传上 GitHub 等于全网公开。
2. node_modules / venv——依赖文件夹，动辄几万文件，别人拿到项目后一条安装命令即可重建。
3. 构建产物和系统垃圾文件，如 dist/、.DS_Store。

7.1环境变量与 .env 文件

一句话定义：环境变量是存在于代码之外、随环境（开发/生产）变化的配置值；.env 文件是项目在本地保存这些值的常用方式。

生活类比：租房时不该刻在墙上的信息。房子（代码）可以给别人看，但 Wi-Fi 密码、门禁卡号（密钥）写在小本子上随身带，换房子换一套。.env 就是这个小本子。

DATABASE_URL=mysql://root:123456@localhost:3306/todo_app
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
JWT_SECRET=a-very-long-random-string
NODE_ENV=development

代码里通过 process.env.OPENAI_API_KEY（Node.js）或 os.getenv(...)（Python）读取这些值。好处：密钥不进代码、不进 Git；同一套代码换一份 .env 就能从开发切到生产。

7.2包与包管理器

一句话定义：包（Package）是别人写好发布的可复用代码；包管理器负责帮你下载、安装、记录版本——JavaScript 用 npm，Python 用 pip。

生活类比：应用商店。你的项目不重复造轮子，需要的功能（日期处理、图表、支付）都"下载 App"装进来。

项目通过两个文件记录依赖：package.json（Node.js）记录项目名字、脚本命令和依赖清单；requirements.txt（Python）一行一个"包名==版本号"。node_modules 文件夹是依赖的实际存放地，体积巨大，永远不进 Git。

7.3版本号：1.2.3 是什么意思

语义化版本：主流包采用 主版本.次版本.修订号 的三段式。修订号变化=修 bug；次版本变化=加功能但兼容；主版本变化=有不兼容的大改动。

package.json 里的 ^1.2.3 表示"自动升级到 1.x 的最新版"。省心但也可能某次升级引入新问题——这就是为什么还会有 package-lock.json：它锁定每个依赖的精确版本，保证所有人和服务器装出的依赖一模一样。lock 文件要提交进 Git，和代码同进退。

7.4常见坑速查

8.1localhost 与端口

localhost：指"本机"。开发时浏览器访问 localhost:3000，意思是"访问我自己电脑上 3000 端口跑着的程序"——只有你自己能访问。

端口（Port）：一台电脑上同时跑着很多程序，端口号用来区分谁来接待这次访问，类比办公楼里的房间号。常见端口：网页 80（HTTP）/443（HTTPS），MySQL 3306，前端开发服务器常用 3000/5173。

报错"端口被占用（EADDRINUSE）"，就是 3000 房间已经有人了：要么关掉旧进程，要么让新程序换个端口。

8.2服务器：一台永远不关机的电脑

一句话定义：部署就是把你的代码从自己的电脑搬到一台 7×24 小时运行、有公网地址的服务器上，让任何人随时能访问。

今天的"服务器"通常指云服务器：向云厂商（阿里云、腾讯云、AWS 等）按量租用一台虚拟电脑，装好运行环境，把代码放上去跑起来。

8.3域名与 DNS

一句话定义：域名是服务器的好记名字（如 myapp.com）；DNS 是把域名翻译成服务器 IP 地址的全球查询系统。

生活类比：手机通讯录。你记的是"妈妈""快递站"，真正拨出去的是电话号码。DNS 就是互联网那本巨大的通讯录。

上线流程里你会做一件事：在域名服务商后台加一条 DNS 记录（常见 A 记录指向服务器 IP，或 CNAME 记录指向托管平台给的地址）。DNS 生效有缓存延迟，等几分钟到几小时都正常。

8.4HTTPS：给通信加把锁

一句话定义：HTTPS 是加密版的 HTTP，地址栏的小锁标志。它保证数据在传输途中不会被偷看、篡改。

现在 HTTPS 已是标配：不加密，浏览器直接警告"不安全"，搜索引擎降权，调用方甚至直接拒绝请求。好消息是，主流托管平台都自动签发免费的 HTTPS 证书；自建服务器可用 Let's Encrypt 免费证书。让 AI 帮你配 Nginx 时，记得加一句"配置 HTTPS 并把 HTTP 自动跳转 HTTPS"。

8.5Docker：把环境打包带走

一句话定义：Docker 把"代码 + 运行环境 + 依赖"整体打包成一个镜像（Image），在任何装了 Docker 的机器上都能原样跑起来。

生活类比：集装箱。以前码头装卸货要看货物形状一个个折腾；有了标准集装箱，船、火车、卡车通用。Docker 之于软件部署，就是集装箱之于航运——"在我电脑上能跑"终于等于"在你电脑上也能跑"。

AI 生成项目根目录里的 Dockerfile 就是打包说明书，docker-compose.yml 则描述"一键同时启动应用+数据库"等多容器组合。初次接触不必深究命令，能认出文件、知道作用即可。

8.6部署方式怎么选

9.1读懂报错信息：三段式定位法

报错不是天书。无论哪种语言，报错信息都有三段：

一长串报错（堆栈信息 Stack Trace）从下往上读，找到第一个属于你自己项目的路径，那里就是事发现场。

9.2日志：程序的黑匣子

一句话定义：日志是程序运行时写下的流水账——什么时候、做了什么、结果如何。线上问题无法复现时，日志是唯一线索。

前端的日志在浏览器控制台（按 F12 打开 Console 面板）；后端的日志在服务器上。给 AI 描述问题时，把控制台的红色报错和服务器日志的对应片段一起贴给它，修复成功率会显著提高。

9.3浏览器开发者工具：Vibe Coder 的显微镜

9.4安全五不要

9.5CORS：浏览器的门卫

一句话定义：CORS（跨域资源共享）是浏览器的安全规则——网页不能随便读取别的域名的数据，除非对方服务器明确许可。

生活类比：小区门禁。你的网页（a.com）想调另一个域名（api.b.com）的接口，就像访客进小区——对方门卫（服务器的 CORS 响应头）点头才放行。

前端报错 blocked by CORS policy，问题几乎都在后端：后端没配 Access-Control-Allow-Origin。把报错贴给 AI 并说明前端域名和后端框架，它会给你对应的放行配置。注意：只允许自己的域名，不要图省事配成允许所有人（*），尤其是带登录态的接口。

10.1描述需求的黄金结构

AI 输出质量的上限，是你输入质量的上限。一个高质量需求描述包含四段：

对比"帮我做个请假系统"，四段式描述得到的代码可以直接用的概率高出一个数量级。

10.2小步快跑：一次只做一件事

让 AI 一次性生成整个应用，得到的往往是处处能跑、处处有坑的半成品。正确节奏是：

1. 第一步：让 AI 搭出最小骨架（能启动、能显示一个页面），跑通就 git commit。
2. 第二步：每次只加一个功能（登录、列表、提交……），每个功能验收通过就 commit。
3. 第三步：某一步改崩了，git 回退到上一个存档，换个描述方式重来——成本几乎为零。

这就是为什么第六章说"勤提交"是 Vibe Coding 最重要的习惯：提交越频繁，试错成本越低。

10.3验收清单：AI 交活后必查五件事

1. 跑起来了吗？——亲手操作一遍核心流程，不只看代码。
2. 有明文密钥吗？——全局搜索 sk-、password、secret。
3. 报错处理了吗？——故意输错、断网，看是友好提示还是白屏崩溃。
4. 数据库操作带 WHERE 吗？——检查 UPDATE/DELETE 的影响范围。
5. 该提交的提交了吗？——git add + commit，给这次进展存档。

10.4十个高频提示词模板