你会遇到的东西

这是什么

和网页版聊天机器人不同，编程助手（也叫 coding agent）直接住在你的项目文件夹里。你说一句话，它能自己去读文件、判断该改哪里、写入改动、运行命令看结果，出错了再自己修一轮。

常见的形态有两种：

• 命令行型（如 Claude Code）—— 在终端里对话，能力最完整，本课的演示以它为准。
• 编辑器型（如 Cursor、Cline）—— 长在 VS Code 里，能看到改动的高亮对比，视觉上更友好。

两种都行。本课不绑定任何一家，任何具备「读写文件 + 执行命令」能力的助手都能跟下来。

为什么你需要它

因为普通聊天机器人给你的是代码片段，你还得自己知道往哪儿贴。对没有代码基础的人来说，那一步恰恰是最难的。

编程助手把这一步接管了。你描述意图，它落地到具体文件。这就是 vibe coding 之所以成立的技术前提。

代价是：它会替你做大量你没看见的决定。所以这门课花很大篇幅教你怎么把话说清楚、怎么检查结果、以及用 Git 兜住它。

几个必须知道的习惯

1. 在项目文件夹里启动它，它的视野就是这个文件夹。
2. 让它一次只做一件事。 “把这三个功能都实现了”通常不如分三轮。
3. 先 Git 提交，再让它大改。 这是唯一可靠的后悔药。
4. 它说”已完成”不等于真的能跑。 自己刷新页面看一眼，这一步不能省。
5. 在项目里放一份 AGENTS.md 说明项目结构，它每次的起点会好很多。

怎么开始

装法各家不同，看环境准备。装完在项目文件夹里启动，第一句话可以是：

看一下这个文件夹，告诉我这是个什么项目、有哪些文件。

先让它读，再让它写。

这是什么

VS Code（全称 Visual Studio Code）是一个免费的文本编辑器，专门为写代码优化过。它长得像一个带侧边栏的记事本：左边是项目的文件树，中间写内容，底部可以直接开一个终端。

为什么你需要它

你需要一个地方看到 AI 到底改了哪些文件、改了什么。VS Code 会用颜色标出新增和删除的行，把报错直接画在出问题的那一行上。对新手来说，它最大的价值不是”写”，而是看懂发生了什么。本课的所有演示都在 VS Code 里进行。

怎么开始

1. 去官网下载对应系统的安装包，双击安装，没有任何需要配置的选项。
2. 装中文语言包：打开左侧的扩展面板（四个方块的图标），搜索 Chinese，装上第一个，重启。
3. 学会一个快捷键就够用了：Ctrl/Cmd + P，输入文件名直接跳过去。
4. 按 Ctrl + ` 打开内置终端——写代码和跑命令在同一个窗口里完成。

这是什么

Sublime Text 是一个以速度著称的编辑器。它启动几乎是瞬间的，打开几百兆的文件也不会卡。界面非常克制，默认什么都没有，需要什么自己装。

为什么你需要它

当你只是想快速打开一个文件看一眼、改一行字，Sublime 比任何工具都快。很多人把它当成”更好的记事本”常驻在系统里，而把 VS Code 留给正式的项目。它可以无限期免费试用，只是偶尔弹一个购买提示。

怎么开始

1. 官网下载安装，不需要注册账号。
2. 试试它的招牌功能：Ctrl/Cmd + D 连续按，可以同时选中文中所有相同的词，一次性改掉。
3. 如果你已经在用 VS Code，这个可以先跳过，等你觉得 VS Code 太重了再回来看。

这是什么

Vim 是一个跑在终端窗口里的编辑器，没有菜单、没有鼠标，全靠键盘。它有个特别的设计：分模式。刚打开时是普通模式，这时按键不是在打字，而是在下命令；按 i 才进入插入模式，这时才能真正输入文字；按 Esc 回到普通模式。

为什么你需要它

两个现实原因。第一，有些命令（比如 Git 提交）会自动弹出 Vim 让你写说明，不知道怎么退出的人会当场卡住。第二，当你以后连服务器时，那里往往只有终端，Vim 是唯一能用的编辑器。

你不需要精通它，但需要能进能出。

逃生咒语

# 想保存
Esc  →  :wq  →  回车     # w = write 写入，q = quit 退出

# 不想保存，直接跑
Esc  →  :q!  →  回车     # 记住这一条，你就永远不会被困住

这是什么

终端是一个只有文字的黑窗口，你在里面输入一行命令，电脑执行它。bash 是负责”听懂”这些命令的翻译官，专业叫法是 shell（外壳）。macOS 现在默认用的是 zsh，它是 bash 的升级版，命令基本通用。

为什么你需要它

本课几乎所有 AI 编程工具都跑在终端里——你跟 AI 的对话就发生在这个黑窗口中。

更重要的是，命令行强迫你把意图说清楚：点哪个按钮可以靠猜，但一条命令要么对要么错。这种精确表达的习惯，和写好 prompt 是同一件事。

够用的六条命令

pwd              # 我现在在哪个文件夹？
ls               # 这个文件夹里有什么？
cd my-project    # 进入 my-project 文件夹
cd ..            # 退回上一层
mkdir site       # 新建一个叫 site 的文件夹
open .           # 在访达里打开当前文件夹（Windows: explorer .）

怎么开始

1. macOS：按 Cmd + 空格，搜索”终端”，回车。Windows：建议先装 WSL2，得到一个和 Mac 几乎一样的环境。
2. 先认三个概念：路径（你现在在哪）、命令（做什么）、参数（对谁做）。
3. 不记得某个命令怎么用？直接问 AI：“在 macOS 终端里怎么把这个文件夹压缩成 zip？”

这是什么

JavaScript 原本只能在浏览器里跑。Node.js 把它带到了你的电脑上，于是 JS 也能读写文件、启动服务器、跑命令行工具。

包管理器（npm / bun）负责另一件事：帮你下载别人写好的代码库。你想加个图表功能，不用从头写，一条命令装一个现成的库就行。这些库统一放在项目的 node_modules 文件夹里——那个文件夹通常巨大，而且不需要提交到 Git。

为什么你需要它

几乎所有现代前端工具都建在 Node 上：AI 编程助手本身、Vite、React、Vue、以及这个课程网站用的 Astro。它不是你要学的东西，是你要有的东西。

package.json 是每个项目的身份证，记录了它依赖哪些库、有哪些可执行的命令。AI 需要判断”这个项目怎么跑起来”时，看的就是它。

常用命令

node --version        # 确认装好了

bun install           # 按 package.json 装齐所有依赖（npm install 同理）
bun add chart.js      # 新装一个库
bun run dev           # 跑项目里定义的 dev 命令，通常是启动开发服务器

# 国内下载卡住时换镜像源
npm config set registry https://registry.npmmirror.com

怎么开始

1. 装 LTS（长期支持）版，别装最新版。见环境准备。
2. 拿到一个新项目，先 bun install，再看 package.json 里的 scripts 有什么命令能跑。
3. 报错里出现 node_modules 或 EACCES？把完整报错交给 AI，这类问题它处理得很好。

这是什么

一种极简的排版写法：用 # 表示标题，** 表示加粗，- 表示列表。写的时候是纯文本，渲染出来是漂亮的排版。

## 二级标题

这是一段话，其中**这几个字是粗的**，这是 `一段代码`。

- 列表第一项
- 列表第二项

> 这是一段引用

为什么你需要它

三个地方你天天会用到：

• README.md —— 每个项目的说明文档，GitHub 会自动渲染它。
• AGENTS.md —— 写给 AI 看的项目说明。
• 你的反思和项目声明 —— 本课要求的文字产出，用它写最方便，因为可以直接进版本库、和代码放在一起。

顺带一提，你正在看的这个网站，所有内容都是 Markdown 写的。

怎么开始

不用专门学，写的时候忘了语法就查速查表。VS Code 打开 .md 文件时按 Cmd/Ctrl + Shift + V 可以看到渲染后的效果。

这是什么

环境变量是存在系统里、程序运行时能读到的键值对。它的用途是把「会变的」和「要保密的」东西从代码里拿出来。

实践上通常写在项目根目录的一个 .env 文件里：

# .env
API_KEY=sk-xxxxxxxx
DATABASE_URL=file:./data.db

代码里通过 process.env.API_KEY 读取，而不是把 sk-xxxxxxxx 直接写在代码中间。

为什么你需要它

因为把密钥写进代码再推到 GitHub，是新手最常见、后果最严重的事故。

公开仓库会被自动扫描，泄露的密钥常在几分钟内被利用。它可能意味着一笔账单，或者一个被人乱发邮件的邮箱。

而且删掉再提交没用——Git 记着所有历史版本。一旦推上去，唯一正确的处理是立刻去平台吊销那个密钥、重新生成一个。

铁律

1. 项目里建一个 .gitignore，第一行写上 .env。
2. 再建一个 .env.example，只写变量名不写值，提交这个，让别人知道需要配什么。
3. 部署到 Cloudflare / Vercel 时，在平台后台的环境变量设置里填，不要放进代码。
4. 前端代码里没有秘密。 打包进浏览器的任何值，用户都能看到。需要保密就必须走后端。

怎么开始

# .gitignore
.env
node_modules/
dist/

不确定某个值该不该藏？问 AI：“这个值如果被别人看到，他能用它做什么？”

这是什么

localhost 就是”这台电脑自己”。当你跑起一个开发服务器，它在你的电脑上启动了一个真正的网站服务，只有你能访问。

端口是同一台电脑上区分不同服务的编号。想象一栋楼只有一个地址，端口就是门牌号：3000 住着你的后端，5173 住着前端开发服务器，它们互不干扰。

http://localhost:5173
       ↑          ↑
    这台电脑    5173 号门

为什么你需要它

几个每天都会撞上的场景：

• “端口被占用了”（EADDRINUSE） —— 上一次的服务还在后台跑着。关掉那个终端窗口，或者换个端口号。
• 手机上打不开 —— 对，localhost 只对本机有效。想用手机测，得用局域网 IP（如 192.168.1.5:5173）。
• 前端调后端报 CORS 错 —— 因为 5173 和 3000 在浏览器眼里是两个不同的”来源”，需要后端明确允许。

理解了这个，你就知道**“在我电脑上是好的”为什么不算数**——它只是在 localhost 上是好的。作品要真的存在，得部署出去。

怎么开始

bun run dev          # 启动后终端会打印一个 localhost 地址，点它

# 端口被占用时，查是谁占着（macOS / Linux）
lsof -i :3000

这是什么

Git 是一个记录文件变化的工具。你在关键节点手动”存档”（叫做 commit 提交），Git 就把整个项目当时的样子完整记下来。之后无论怎么改，你都可以随时翻回任何一个存档点。

为什么你需要它

这是 vibe coding 的安全网。 AI 一次改动可能涉及十几个文件，如果结果不对，没有 Git 你只能干瞪眼。有了 Git，你可以放心大胆地让 AI 试各种方案——反正一条命令就能撤回。

日常只用这几条

git init                     # 开始管理这个文件夹
git status                   # 看看哪些文件改了
git add .                    # 把所有改动放进待提交区
git commit -m "加上深色模式"   # 存档，并写清楚做了什么
git log --oneline            # 看历史存档列表
git restore .                # 反悔：丢掉未提交的所有改动

怎么开始

1. 在项目文件夹里执行 git init，从此这个文件夹被 Git 管起来了。
2. 养成节奏：AI 改完一轮 → 你确认能跑 → 提交一次。别攒着一次提交。
3. 提交说明用人话写清楚”这次做了什么”，比如”加上了深色模式”，别写 update。
4. 完全可以让 AI 代劳：直接说”帮我把当前改动提交，写一条合适的说明”。

这是什么

GitHub 是全球最大的代码托管网站。你把本地的 Git 存档”推”上去（push），它就在云端保存一份。每个项目叫一个仓库（repository），别人可以浏览、提问（issue）、甚至提交修改建议（pull request）。

为什么你需要它

三件事离不开它：

• 备份 —— 电脑丢了项目还在。
• 发布 —— 开启 GitHub Pages，静态网站立刻拥有一个免费网址。
• 履历 —— 对创作者来说，一个持续更新的 GitHub 主页比简历上任何一句自我描述都有说服力。

第一次把项目推上去

git remote add origin https://github.com/你的用户名/项目名.git
git branch -M main
git push -u origin main

# 以后每次改完只要
git push

怎么开始

1. 注册账号。用户名会出现在你所有作品的网址里，起一个你愿意长期用的。
2. 新建仓库，按页面上给的命令把本地项目推上去；卡住了就把整段报错贴给 AI。
3. 在仓库 Settings → Pages 里，把来源设为主分支，等一分钟，网址就生效了。
4. 给每个项目写一个 README.md：这是什么、怎么跑起来、放两张截图。

这是什么

Cloudflare 在全球有几百个机房。当你的网站接入它之后，访问者会就近从最近的机房拿到内容，而不是绕地球找你的服务器。它同时还挡下攻击流量、免费提供 HTTPS 证书。其中 Pages 可以直接托管网站，Workers 可以跑一小段后端逻辑。

为什么你需要它

对本课来说它解决两个具体问题：

1. GitHub Pages 在国内访问不稳定，用 Cloudflare Pages 部署同一个仓库通常快很多，而且推送代码后自动重新部署。
2. 当你的项目需要一点点后端——比如藏一个 API 密钥、存几条留言——Workers 的免费额度完全够用，不需要租服务器。

怎么开始

1. 注册后进入 Workers & Pages → 创建 → Pages → 连接你的 GitHub 仓库。
2. 构建命令和输出目录如果不确定，把项目的 package.json 贴给 AI 让它告诉你填什么。
3. 每次 git push 之后，Cloudflare 会自动构建并上线，网址不变。
4. 想用自己的域名：在 Custom domains 里添加，HTTPS 证书会自动签发。

这是什么

React 是 Meta 开源的界面库。它的核心想法很简单：界面 = 数据经过一个函数变成的结果。你不再手动去命令”把这个按钮的文字改成 X”，而是改变数据，React 自己算出界面该长什么样并更新。写法上它把结构和逻辑放在同一个文件里，叫做 JSX。

为什么你需要它

React 是目前生态最大的选择——你想要的任何东西（图表、动画、地图、富文本编辑器）几乎都有现成的 React 版本，AI 对它的训练数据也最多，生成的代码质量最稳定。当你的项目从”一个页面”长成”一个应用”，组件化会让你不至于失控。

怎么开始

1. 先别急着学。 第一个作品用纯 HTML 完成，等你开始重复复制粘贴同一段结构时，再引入它。
2. 起步：bun create vite@latest my-app -- --template react
3. 只需理解两个概念：组件（一段可复用的界面）和状态（会变化的数据）。
4. 让 AI 解释它生成的代码时，明确要求：“逐段解释这个组件，假设我没写过 JavaScript。”

这是什么

Vue 由尤雨溪创建，解决的问题和 React 一样，风格不同：它把结构（template）、逻辑（script）、样式（style）分三块写在同一个文件里，看起来更像你熟悉的 HTML。中文文档和社区非常完整。

为什么你需要它

如果你完全没有编程背景，Vue 的模板语法通常更容易读懂——v-if、v-for 这种写法几乎是在读英语。它在国内的使用率很高，遇到问题搜到中文答案的概率更大。

React 和 Vue 选哪个都行，重要的是选一个就别来回换。

怎么开始

1. 起步：bun create vite@latest my-app -- --template vue
2. 先看官方文档的”快速上手”，跟着敲一遍计数器例子。
3. 让 AI 帮你写时说清楚：“用 Vue 3 组合式 API 和 <script setup> 写。“不说清楚它可能给你老版本的写法。

这是什么

数据库就是一个专门用来存东西、并且能快速找出来的地方。

最容易理解的模型是表格：每张表像一个 Excel sheet，每一列是一个字段（谁、说了什么、什么时候），每一行是一条记录。

messages 表
┌────┬──────────┬────────────────┬─────────────────────┐
│ id │ author   │ content        │ created_at          │
├────┼──────────┼────────────────┼─────────────────────┤
│ 1  │ 小满     │ 第一条留言     │ 2026-03-01 10:00    │
│ 2  │ 阿远     │ 你好           │ 2026-03-01 10:05    │
└────┴──────────┴────────────────┴─────────────────────┘

SQLite 是其中最省事的一种：整个数据库就是一个文件，不需要单独安装和启动任何服务。对本课的项目规模来说，它完全够用，而且够用很久。

为什么你需要它

你当然可以把数据存成一个 JSON 文件——第一版这么做完全没问题。但很快会遇到：

• 数据多了以后，每次读取都要把整个文件加载进内存
• 两个人同时提交，后写的会覆盖先写的
• 想查”最近七天的记录”，得自己写一堆筛选逻辑

数据库把这些问题一次性解决了。它是「玩具项目」和「能给人用的项目」之间的分界线之一。

一点 SQL

数据库用一种叫 SQL 的语言查询。你不需要会写，但看懂它在干嘛很有用：

SELECT * FROM messages WHERE author = '小满' ORDER BY created_at DESC LIMIT 10;
-- 从 messages 表里，找出作者是小满的记录，按时间倒序，取前 10 条

念一遍你会发现它几乎就是英语。

怎么开始

1. 第一版先用 JSON 文件跑通流程，感受一下它哪里不够用。
2. 然后跟 AI 说：“把存储换成 SQLite，顺便解释一下表结构是怎么设计的、为什么这么设计。”
3. 重点看它设计的表结构——这是少数你应该看懂并且有权反对的地方。字段起什么名、要不要拆成两张表，这些决定会一直影响后面。

这是什么

一种写数据的格式，长这样：

{
  "name": "林小满",
  "city": "上海",
  "skills": ["设计", "摄影"],
  "active": true,
  "projects": [
    { "title": "一个网站", "year": 2026 }
  ]
}

规则少到一眼能看完：大括号是对象（一组键值对），中括号是数组（一列东西），值可以是文字、数字、真假、或者嵌套的对象和数组。

为什么你需要它

你会在至少四个地方遇到它：

• API 返回的数据 —— 你调一个接口，回来的基本都是 JSON。
• 配置文件 —— package.json 就是。
• 前后端之间传的东西 —— 提交表单、返回结果。
• 导出你自己的数据 —— 很多平台的数据导出都是 JSON。

看懂它，你就能自己判断”这个接口到底给了我什么”，而不是把一坨东西整个丢给 AI 说”你看着办”。

一个实用技巧

拿到一大坨看不懂的 JSON，浏览器 F12 的 Network 面板会自动折叠成树形，比在终端里看清楚得多。

或者直接问 AI：

这是某接口返回的 JSON（贴在下面）。
帮我列个表：有哪些字段、每个字段是什么意思、哪些是我做这个可视化需要的。

常见的坑

• 末尾不能有多余的逗号，这是 JSON 报错最常见的原因。
• 键必须用双引号包起来，单引号不行。
• 报错信息会告诉你出问题的字符位置，把它连同文件一起交给 AI 就行。

这是什么

HTTP 是浏览器向服务器要东西的一套规矩：浏览器发出一个请求（我要 /about 这个页面），服务器返回一个响应（这是内容，状态码 200 表示成功）。

HTTPS 就是加了一层加密的 HTTP——中间的人能看到你在跟哪个网站说话，但看不到说了什么。地址栏里的小锁就是它。

为什么你需要它

当你的项目开始连接外部数据（比如调一个天气接口），你面对的就是 HTTP 请求。看懂 404、500、CORS，你就能准确地告诉 AI 问题出在哪一层，而不是只会说”它坏了”。

另外，现在的浏览器基本只信任 HTTPS——摄像头、麦克风、定位这些能力，在纯 HTTP 的页面上会被直接禁用。

认识几个状态码

码	意思
200	成功
301 / 302	跳转到别处了
404	这个地址不存在
500	服务器自己出错了

怎么开始

1. 在浏览器里按 F12 打开开发者工具，切到 Network（网络）标签，刷新页面，你会看到每一次请求。
2. 记住这个区分：前端跑在别人的浏览器里，后端跑在你的服务器上，HTTP 是它们之间唯一的通道。
3. 遇到报错，把 Network 面板里那条红色请求的完整信息复制给 AI，它基本能直接定位。

# 用终端发一个请求，看看服务器回了什么
curl -i https://example.com

这是什么

SMTP（简单邮件传输协议）是服务器之间投递邮件的规矩，诞生于 1982 年，至今没变。当你的项目需要”提交后给我发一封邮件”，代码要做的就是连上一台 SMTP 服务器，出示用户名密码，然后把收件人、标题、正文交给它。

为什么你需要它

这是你的作品第一次主动联系一个真人。表单提交通知、验证码、订阅更新——背后都是它。

同时它也是一个很好的观察对象：邮件是少数不属于任何一家公司的互联网基础设施，任何人都可以自己架一台服务器发信。这和课程后半段要讨论的平台垄断形成鲜明对照。

怎么开始

1. 别自己架服务器，自己发的信基本都会进垃圾箱。用 Resend、SendGrid 这类服务，或者你邮箱提供商给的 SMTP 地址。
2. 需要四个信息：服务器地址、端口（一般是 465 或 587）、账号、授权码。注意授权码不是你的登录密码，要去邮箱设置里单独生成。
3. 这些信息绝对不能写进代码里推到 GitHub。
4. 发不出去时先看端口和授权码，九成的问题都在这两处。

# .env  ← 记得把这个文件写进 .gitignore
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=me@example.com
SMTP_PASS=授权码不是登录密码

这是什么

OAuth 2.0 解决一个问题：怎么让 A 网站代表你去访问 B 网站上的数据，而不需要你把 B 的密码交给 A。

流程是这样的——你被跳转到 B，在 B 自己的页面上登录并确认授权，B 发回一个令牌（token）给 A。A 全程拿不到你的密码，而且这个令牌可以随时被你撤销。

为什么你需要它

技术上，你的项目一旦需要登录，自己存密码是件危险且没必要的事，接第三方登录更安全。

批判层面，OAuth 也是平台把用户圈进生态的机制：你的账号越是绑定在几家大公司上，迁移的成本就越高。这正是课程后半段「谁拥有这些工具」要追问的东西。

怎么开始

1. 去平台的开发者后台注册一个应用，拿到 Client ID 和 Client Secret。
2. 记住 Secret 只能待在后端。 前端代码是公开的，任何人都能看到里面的内容。
3. 优先用现成的库（比如 Auth.js），不要自己手写整个流程，容易留下安全漏洞。
4. 让 AI 帮你接的时候，明确问一句：“这个方案里哪些值是不能暴露在前端的？”

这是什么

Passkey 是密码的替代方案。注册时，你的设备生成一对钥匙：私钥留在手机或电脑的安全芯片里永不外传，公钥交给网站。登录时网站出一道题，只有持有私钥的设备能解出来——而解锁私钥靠的是你的指纹或面容。

整个过程没有任何”密码”被传输或存储。

为什么你需要它

这是理解现代安全思路的最好例子：与其保护一个秘密不被偷走，不如让秘密根本不需要离开你的设备。

它天然免疫钓鱼网站——私钥和域名绑定，假网站根本触发不了。作为创作者，你会越来越多地在自己的项目里遇到这个选项，值得知道它比”存一堆密码哈希”好在哪里。

怎么开始

1. 先当用户体验一次：去 GitHub 的账号安全设置里添加一个 passkey，然后退出重新登录感受流程。
2. 自己的项目要实现，用 SimpleWebAuthn 这类库，别从底层 API 开始写。
3. 设计时记得留后路：用户换手机怎么办？通常做法是同时保留邮箱验证作为备用登录方式。