从零开始 · TypeScript 全栈 · 用 Claude 开发
72 个学习日，每天 5–6 小时，学 6 天休 1 天，12 周学完。每一天都配了完整课件：学习目标、上午的讲解和代码示例、下午的分步实操、常见问题、晚上的验收题和参考答案。点开任意一天，照着课件一步一步学就行。用一门语言（TypeScript）从网页一路写到后台和 AI 功能，每个阶段结束都上线一个你自己用得上的作品。
第一天预告 · DAY 01
2026 年 9 月 28 日开始。开始日期可以在上方改。
上午 · 学（2.5 小时）
了解前端、后端、数据库各管什么；安装 Homebrew、Node.js（LTS 版）、Git、VS Code，给 VS Code 装中文语言包、Prettier、ESLint 插件
下午 · 做（2.5 小时）
终端练习 cd、ls、pwd、mkdir、touch、cat、mv、rm、grep、which：建一个 learn 文件夹，在里面建文件、改名、删除；在 Claude Code 里把输出风格切到 Learning
晚上 · 验收（0.5–1 小时）
不看笔记，在终端新建文件夹 day1，进去建 hello.txt，写入一句话，再把内容显示出来。
为什么这样排
路线图
第一排是学什么，第二排是这段时间 Claude 扮演的角色，第三排是每次上线的作品。每一格是半周（3 个学习日），点色块可以跳到对应阶段。
每日节奏
上午 · 学
2.5 小时
看教程、跟着敲例子。脑子最清醒的时候留给新概念，每 50 分钟起来休息 10 分钟。
下午 · 做
2.5 小时
做当天的练习或作品。遇到问题先自己查 15 分钟，再问 Claude。
晚上 · 验收
0.5–1 小时
回答当天的验收题，点“让 Claude 考我”，写学习笔记，然后打勾。
每天点开当天的课件，按“上午课件 → 下午动手 → 晚上验收”的顺序学。某一天没学完，就顺延到第二天，不要跳过。整体推迟时，把上方的开始日期往后改，所有日期会跟着重算。每学 6 天完整休息 1 天。
技术栈
都是资料多、Claude 写得熟练、对新手友好的选择。先把这一套用熟，以后换别的工具会很快。
| 层 | 选择 | 为什么 |
|---|---|---|
| 语言 | TypeScript（先学 JavaScript） | 浏览器和服务器都能跑；类型检查能帮你抓出自己和 AI 写错的地方 |
| 全栈框架 | Next.js | 页面和后端接口写在同一个项目里，一次部署 |
| 界面 | React + Tailwind CSS | 最主流的组合，教程和现成组件最多 |
| 数据库 | PostgreSQL（Neon 托管）+ Prisma | 不用自己装数据库、管服务器；Prisma 的表结构写法新手也能看懂 |
| 登录 | Better Auth | 现成的登录方案，不用自己从零写密码和会话 |
| 输入校验 | Zod | 一份规则同时管前端表单和后端接口 |
| 图片存储 | Vercel Blob | 上传 look 照片，和部署平台是同一家 |
| 测试 | Vitest + Playwright | 一个测函数，一个模拟真人在浏览器里点 |
| 部署 | GitHub + Vercel | push 代码自动上线，有新加坡节点 |
| AI | Claude Code + Claude API | 开发时用 Claude Code 写代码；产品里用 @anthropic-ai/sdk 调用 Claude |
Claude 协作阶梯
一开始就让 Claude 写全部代码，你会得到能跑的项目，但学不会编程。所以前期限制它，后期放开它。
/code-reviewgit commit/code-review 三件套讲不清，就让 Claude 解释到你讲得清为止。这一条贯穿整个计划。
阶段 0 · DAY 01–03 · 约 3 天
装好所有工具，学会终端和 Git，头 3 天就把你现在的官网放到网上。
第 1 周
上午 · 学了解前端、后端、数据库各管什么；安装 Homebrew、Node.js（LTS 版）、Git、VS Code，给 VS Code 装中文语言包、Prettier、ESLint 插件
下午 · 做终端练习 cd、ls、pwd、mkdir、touch、cat、mv、rm、grep、which：建一个 learn 文件夹，在里面建文件、改名、删除；在 Claude Code 里把输出风格切到 Learning
晚上 · 验收
不看笔记，在终端新建文件夹 day1，进去建 hello.txt，写入一句话，再把内容显示出来。
上午 · 学Pro Git 第 1–2 章：仓库、暂存区、提交、查看历史，以及分支是什么
下午 · 做注册 GitHub 并在终端登录；把 learn 文件夹变成仓库，提交 5 次，推到 GitHub
晚上 · 验收
讲清 git add 和 git commit 的区别；故意改坏一个文件，再用 Git 恢复它。
上午 · 学一次网页访问的全过程：域名、DNS、HTTP 请求和响应、状态码；Vercel 是做什么的
下午 · 做把桌面上的 dongge-site 文件夹推成 GitHub 仓库，导入 Vercel 得到网址；改一行字再 push，看网站自动更新
晚上 · 验收
用自己的话讲一遍：在手机上打开官网网址，到页面出现，中间发生了什么？
阶段毕业标准
能在终端新建项目、提交到 GitHub，并通过 push 更新线上网站；能向 Claude 说清楚“我想做什么、卡在哪一步”。
资源
阶段 1 · DAY 04–12 · 约 1.5 周
亲手写出一个在手机上好看的页面。你的粉丝几乎都在手机上刷到你，所以手机效果永远排第一。
第 1 周
上午 · 学MDN 的 HTML 入门：标题、段落、链接、图片、列表；标签、属性、嵌套
下午 · 做手写一个“关于东哥”页面：一段介绍、三个世界的列表、一张图片、四个平台链接
晚上 · 验收
块级元素和行内元素有什么区别？各举 3 个例子。
上午 · 学header、nav、main、section、footer 各用在哪；表单元素 input、textarea、select、button、label
下午 · 做写「链接主页」骨架：头像、一句话介绍、小红书 / TikTok / Facebook / Instagram 四个按钮，再加一个“给东哥留言”表单（先不提交）
晚上 · 验收
为什么按钮要用 button 而不是 div？为什么 input 要配 label？
上午 · 学选择器、颜色、字体、单位（px、rem、%）、盒模型（margin、border、padding）
下午 · 做给链接主页加样式：字体、颜色、按钮圆角和间距；用浏览器开发者工具查看每个元素的盒模型
晚上 · 验收
margin 和 padding 有什么区别？用开发者工具找出页面上任意一处间距是哪行 CSS 造成的。
第 2 周
上午 · 学Flexbox：主轴、交叉轴、justify-content、align-items、gap、flex-wrap；通关 Flexbox Froggy
下午 · 做用 Flexbox 排链接主页：头像和名字居中，平台按钮在手机上竖排、在电脑上横排
晚上 · 验收
不看资料，把一个方块放到页面正中间（水平垂直都居中）。
上午 · 学Grid：grid-template-columns、fr、gap；媒体查询与“手机优先”的写法；通关 Grid Garden
下午 · 做做“三个世界”区块：手机一列、平板两列、电脑三列
晚上 · 验收
什么时候用 Flexbox，什么时候用 Grid？各举一个你页面上的例子。
上午 · 学CSS 变量、transition 过渡、hover 状态、用 Google Fonts 引入字体
下午 · 做给绅士、街头、泰风各定一套颜色变量和字体，手动切换 class 看三种效果
晚上 · 验收
用 CSS 变量有什么好处？现场演示：改一个变量，整页颜色一起变。
上午 · 学打开现在官网的源码，和 Claude 逐段读 CSS，每段写一句中文注释
下午 · 做把官网里你喜欢的写法（字体组合、大标题、滚动字幕）用到链接主页上
晚上 · 验收
随便指官网上一个元素，说出是哪几行 CSS 让它长成这样。
上午 · 学viewport 设置、图片自适应、按钮点击区域的大小；开发者工具的手机模拟模式
下午 · 做在自己手机上打开链接主页，把所有别扭的地方列成清单，逐个修掉
晚上 · 验收
在最小的手机屏幕上，页面没有横向滚动，每个按钮都好点。
上午 · 学复习本阶段笔记；让 Claude 审查你的 HTML 和 CSS，只列问题不改代码
下午 · 做修完问题，部署到 Vercel，得到一个可以放进各平台简介的网址
晚上 · 验收
不看教程，30 分钟内从零写出一个居中的名片页。
阶段毕业标准
不看教程写出一个手机上好看的单页；能讲清 Flexbox 和 Grid 各适合什么场景。
资源
阶段 2 · DAY 13–24 · 约 2 周
学会编程的核心：变量、条件、循环、函数、数据。这是整份课表里最重要的两周，后面所有东西都建立在它上面。
第 3 周
上午 · 学现代 JavaScript 教程“JavaScript 基础知识”一章的前半部分：变量、数据类型、类型转换、运算符
下午 · 做在浏览器控制台和 .js 文件里做 10 道小练习：温度换算、计算年龄、拼接一句自我介绍
晚上 · 验收
let 和 const 有什么区别？"5" + 3 和 "5" - 3 分别得到什么，为什么？
上午 · 学if、else、switch、三元运算符；for、while 循环；逻辑运算符 &&、||、!
下午 · 做写 FizzBuzz、猜数字小游戏、打印九九乘法表
晚上 · 验收
不看资料写出 FizzBuzz。
上午 · 学函数声明、参数、返回值、箭头函数、作用域
下午 · 做把昨天的练习都改写成函数；写一个 formatDate 函数，把日期变成“10月1日 周四”
晚上 · 验收
参数和返回值分别是什么？举一个“函数忘了 return”导致出错的例子。
上午 · 学数组的增删改查；forEach、map、filter、find、includes
下午 · 做准备一个 looks 数组（名字、世界、颜色），用 map 生成标题列表，用 filter 筛出“街头”
晚上 · 验收
map 和 forEach 有什么区别？什么时候用 filter，什么时候用 find？
上午 · 学对象的创建、读写、遍历；对象数组；解构赋值；展开运算符 ...
下午 · 做把四个平台做成对象数组（名称、链接、颜色），写一个按名称查找平台的函数
晚上 · 验收
user.name 和 user["name"] 分别在什么时候用？
上午 · 学复习本周笔记，让 Claude 根据你的笔记出 10 道综合题
下午 · 做用 Node.js 运行一个文字版“你最需要哪个东哥”：固定一组答案，算出得分最高的世界
晚上 · 验收
两个世界同分时，你的计分函数会怎样？应该怎样？
第 4 周
上午 · 学现代 JavaScript 教程第二部分“Document”：选中元素、改文字和样式、创建和删除元素
下午 · 做用 JavaScript 从 looks 数组生成卡片，插入到页面里
晚上 · 验收
textContent 和 innerHTML 有什么区别？为什么把用户输入直接放进 innerHTML 很危险？
上午 · 学addEventListener、点击和输入事件、事件对象、事件冒泡与委托
下午 · 做给链接主页加风格切换按钮：一点就换成绅士、街头或泰风；用 localStorage 记住访客的选择
晚上 · 验收
用你自己的页面举例，解释事件冒泡。
上午 · 学表单的 submit 事件、preventDefault、读取输入值、简单校验
下午 · 做完成“给东哥留言”表单的前端校验：不能为空、限制长度、提交后显示感谢（先存在 localStorage）
晚上 · 验收
提交表单时为什么通常要调用 preventDefault？
上午 · 学回调、Promise、async/await、JSON、fetch；用 try/catch 处理错误
下午 · 做把平台链接和介绍文字挪进 data.json，用 fetch 读取后显示；故意写错文件名，显示友好的出错提示
晚上 · 验收
用点外卖打比方，讲清 Promise 和 async/await。
上午 · 学import / export；npm 是什么；package.json；用 Vite 创建一个原生 JavaScript 项目
下午 · 做开始做测试小游戏：写好 6 道题的数据，一题一题显示，记录答案
晚上 · 验收
npm install 做了什么？node_modules 为什么不提交到 Git？
上午 · 学完成计分和结果页：显示对应的世界和一句话，文案守住“说事情不说情话”
下午 · 做把结果做成适合手机截图分享的卡片，部署上线
晚上 · 验收
请两位朋友在手机上做一遍，记下他们卡住或觉得别扭的地方。
阶段毕业标准
能用 JavaScript 独立做出一个有交互、有数据的小页面；能讲清同步和异步的区别。
资源
阶段 3 · DAY 25–36 · 约 2 周
给代码加上类型，用组件的方式搭页面，把官网重做成 React 版。
第 5 周
上午 · 学TypeScript Handbook：基本类型、类型推断、数组和对象的类型、函数的类型
下午 · 做把测试小游戏改写成 TypeScript，逐个修掉编辑器报的错
晚上 · 验收
TypeScript 是在写代码时报错，还是在用户打开网页时报错？这对你有什么好处？
上午 · 学interface 和 type、可选属性、联合类型、字面量类型、泛型入门
下午 · 做给 Look、Platform、QuizQuestion 定义类型；用字面量类型规定世界只能是 gentleman、street、thai 之一
晚上 · 验收
interface 和 type 你会怎么选？联合类型帮你防住了什么错误？
上午 · 学React 中文文档“快速入门”：组件、JSX、props；用 Vite 创建 React + TypeScript 项目
下午 · 做把链接主页拆成 Avatar、Intro、PlatformButton 三个组件
晚上 · 验收
组件是什么？PlatformButton 为什么要通过 props 接收链接和名称？
上午 · 学渲染列表和 key；条件渲染；组件组合与 children
下午 · 做用 looks 数据渲染卡片列表；没有数据时显示一个空状态
晚上 · 验收
列表为什么需要 key？用数组下标当 key 会有什么问题？
上午 · 学useState、事件处理、为什么不能直接修改 state、state 更新后何时生效
下午 · 做用 React 的 state 重做风格切换；再加一个“只看某个世界”的筛选
晚上 · 验收
props 和 state 有什么区别？
上午 · 学受控组件与表单处理；useEffect 的用途和依赖数组
下午 · 做用 React 重写留言表单；用 useEffect 把风格选择存进 localStorage
晚上 · 验收
useEffect 的依赖数组写空数组、不写、写变量，分别会怎样？
第 6 周
上午 · 学状态提升、组件之间传数据；让 Claude 在 Plan 模式出组件树方案，代码你自己写
下午 · 做实现题目组件、进度条、结果页
晚上 · 验收
“当前第几题、选了什么”这些 state 放在哪个组件里？为什么？
上午 · 学Tailwind 的思路；常用类：间距、颜色、字体、flex、grid、响应式前缀 sm: md: lg:
下午 · 做用 Tailwind 重做链接主页的样式
晚上 · 验收
Tailwind 的 md: 前缀是什么意思？
上午 · 学规划新官网的页面：首页、三个世界、链接页、测试入口；画出组件树
下午 · 做搭好首页和导航，尽量复用已经写好的组件
晚上 · 验收
哪些组件在多个页面复用了？
上午 · 学React Router：多页面、Link、动态路由 /world/:id
下午 · 做做三个世界的详情页，数据都来自同一个 TypeScript 文件
晚上 · 验收
为什么三个世界共用一个页面组件，而不是写三个页面？
上午 · 学图片优化、加载状态、404 页面；用 /code-review 审查组件
下午 · 做按审查意见修改，在手机上逐页检查
晚上 · 验收
说出审查意见里你接受的 2 条和不接受的 1 条，以及理由。
上午 · 学上线前检查：构建没有报错、手机显示正常、所有链接都能点
下午 · 做部署上线，替换旧的静态版官网
晚上 · 验收
不看教程，从零建一个 React 项目，做出一个带筛选的列表。
阶段毕业标准
能把一个设计稿拆成组件并用 React 实现；能讲清 props 和 state 的区别。
资源
阶段 4 · DAY 37–54 · 约 3 周
从“会做页面”变成“会做产品”。给官网加上数据库、管理员登录、内容后台和粉丝提问箱。时间给得最多，是整份课表的核心。
第 7 周
上午 · 学Next.js 官方教程开头几章：创建项目、样式、字体和图片、页面与布局
下午 · 做跟着教程把示例项目的骨架做出来
晚上 · 验收
在 Next.js 里，文件夹结构怎么决定网址？
上午 · 学Link、动态路由、嵌套布局、loading 和 not-found 页面
下午 · 做继续教程；同时新建 dongge-web 项目，把 React 版官网的页面迁移过来
晚上 · 验收
layout 和 page 有什么区别？
上午 · 学服务端组件和客户端组件的区别；什么时候要加 "use client"
下午 · 做完成官网迁移：决定哪些组件留在服务端，哪些必须放到客户端（比如测试小游戏）
晚上 · 验收
测试小游戏为什么必须是客户端组件？
上午 · 学数据库、表、行、列；CREATE TABLE、INSERT、SELECT、WHERE、ORDER BY、UPDATE、DELETE
下午 · 做在 Neon 建一个 PostgreSQL 数据库（选新加坡区域），在它的 SQL 编辑器里手写 20 条练习
晚上 · 验收
写一条 SQL：查出所有“街头”世界的 look，按时间从新到旧排。
上午 · 学主键、外键、一对多关系、JOIN；索引是做什么的
下午 · 做设计 worlds、looks、questions 三张表，画出关系图，让 Claude 审查
晚上 · 验收
looks 和 worlds 是什么关系？外键应该放在哪张表？
上午 · 学Prisma：schema 写法、迁移、用 Prisma Client 增删改查
下午 · 做用 Prisma 建好三张表，写一个种子数据脚本，首页改为从数据库读取 looks
晚上 · 验收
改了 schema 之后要做什么，数据库才会跟着变？
第 8 周
上午 · 学Server Actions 与表单；revalidatePath；Route Handlers 是什么
下午 · 做做「粉丝提问箱」：粉丝提交的问题存进数据库
晚上 · 验收
表单提交后，数据是怎么从浏览器一路走到数据库的？
上午 · 学用 Zod 定义规则；为什么服务端校验必不可少；怎么把错误信息返回给表单
下午 · 做给提问箱加校验和提示：长度限制、空内容、防止连点重复提交
晚上 · 验收
只在前端校验为什么不够？
上午 · 学.env 与密钥管理、Vercel 的环境变量；XSS、CSRF、SQL 注入的原理
下午 · 做让 Claude 扮演攻击者检查提问箱，只讲问题和原理，你自己修
晚上 · 验收
XSS 是怎么发生的？React 默认帮你挡住了哪一部分？
上午 · 学认证和授权的区别；Session 与 Cookie；Better Auth 快速上手
下午 · 做接入 Better Auth，做好管理员登录页
晚上 · 验收
认证和授权有什么区别？密码为什么绝不能明文存储？
上午 · 学在服务端检查登录状态；未登录跳转到登录页
下午 · 做建后台首页 /admin，只有你登录后才能进；加上退出登录
晚上 · 验收
有人直接在浏览器输入 /admin 会怎样？有人绕过页面直接调用你的 Server Action 呢？
上午 · 学列表页、表单复用、编辑与删除、删除前确认
下午 · 做完成 looks 的新建、编辑、删除；表格和表单的样板代码交给 Claude，业务逻辑你自己写
晚上 · 验收
删除操作为什么要在服务端再检查一次登录状态？
第 9 周
上午 · 学文件上传的原理；Vercel Blob；限制图片大小和格式
下午 · 做look 支持上传照片，并在前台显示
晚上 · 验收
为什么要在服务端限制文件的大小和类型？
上午 · 学用状态字段表示待审核、已通过、已隐藏；按状态筛选
下午 · 做后台审核提问，通过后才在前台显示；你可以给每条写回答
晚上 · 验收
为什么不直接删掉不想展示的提问，而是用状态字段？
上午 · 学测试是什么；Vitest；先测纯函数：计分、日期格式、校验规则
下午 · 做给测试小游戏的计分和 Zod 规则写 15 个测试
晚上 · 验收
你写的测试里，哪一个最能防止以后不小心改坏东西？
上午 · 学Playwright：模拟真人打开页面、填表、点击
下午 · 做写 3 条流程测试：粉丝提交提问、管理员登录、发布 look 后前台能看到
晚上 · 验收
单元测试和端到端测试各适合测什么？
上午 · 学GitHub Actions；分支加 Pull Request 的工作流
下午 · 做配置 CI：每次 push 自动跑类型检查、测试和构建；从今天起改功能都走 Pull Request
晚上 · 验收
故意让一个测试失败，读懂 CI 日志里的报错。
上午 · 学全项目跑 /code-review，修完高优先级问题
下午 · 做把数据库迁移到正式环境，上线；以后更新内容不用再改代码
晚上 · 验收
不看代码，讲一遍：在后台新增一条 look，从点“保存”到前台出现，经历了什么。
阶段毕业标准
能独立做出“前台 + 后台 + 数据库 + 登录”的网站；能讲清一次表单提交从浏览器走到数据库的全过程。
资源
阶段 5 · DAY 55–63 · 约 1.5 周
在自己的产品里接入 Claude，做一个帮你写文案的助手，再加一个看各平台数据的看板。这部分只有你能登录使用。
第 10 周
上午 · 学大模型 API 是什么：token、系统提示词、上下文；申请 API Key，在控制台设好用量上限，Key 只放进服务端环境变量
下午 · 做用 @anthropic-ai/sdk 写一个最小接口：输入一句话，返回 Claude 的回答
晚上 · 验收
API Key 如果写进浏览器端代码，会发生什么？
上午 · 学流式输出的原理；在 Next.js 里把回答一段段推到页面
下午 · 做做一个简单的对话页：回答逐字显示，可以中途停止
晚上 · 验收
为什么流式输出会让人感觉更快？
上午 · 学写系统提示词的方法：角色、背景、要求、示例、输出格式
下午 · 做为文案助手写系统提示词：人设、女性观众视角、“说事情不说情话”、小红书和 TikTok 的风格差异
晚上 · 验收
你的提示词里，删掉哪一句后输出变差得最明显？
上午 · 学结构化输出：让 Claude 按固定格式返回标题、正文、标签
下午 · 做做文案助手页面：选一个世界、输入视频主题，生成小红书和 TikTok 两版草稿
晚上 · 验收
用 5 个真实主题测试，每条输出打 1–5 分，记下问题。
上午 · 学把生成结果存进数据库；控制成本：限制输入长度和每天的使用次数
下午 · 做草稿可以收藏、修改、标记“已发布”；根据昨天的打分改提示词，再测一轮
晚上 · 验收
改完提示词后平均分提高了吗？哪一处改动最有效？
上午 · 学埋点的思路；怎么防止刷量；按天汇总数据
下午 · 做记录四个平台按钮的点击次数，以及测试小游戏的结果分布
晚上 · 验收
一个人连点 100 次按钮，你的统计会变成什么样？
第 11 周
上午 · 学图表库 Recharts 入门；按周汇总数据的 SQL
下午 · 做在后台做看板：每周各平台的点击数、各个世界在测试结果里的占比
晚上 · 验收
看板上你最想每周看的一个数字是什么？为什么？
上午 · 学后台的导航和布局；整理目录和代码结构
下午 · 做把文案助手和看板合成「东哥内容工作台」
晚上 · 验收
让 Claude 通读代码，指出结构上最该改的一处。你同意吗？为什么？
上午 · 学给 AI 功能写测试（模拟 API 的返回）；跑 /code-review
下午 · 做上线自用，接下来一周真的用它来写文案
晚上 · 验收
用工作台生成的文案，至少有一条真的发出去了。
阶段毕业标准
能在自己的产品里调用 AI；能判断 AI 的输出好不好，知道怎么通过改提示词让它变好。
资源
阶段 6 · DAY 64–72 · 约 1.5 周
把前面做的所有东西打磨成一个快、稳、安全的正式产品，绑定域名，正式对外。
第 11 周
上午 · 学回看所有功能，写正式版的需求文档：保留什么、改什么、明确不做什么
下午 · 做写好 CLAUDE.md 和 README；在 Plan 模式出改进方案，拆成 GitHub issue
晚上 · 验收
正式版必须有的 3 个功能，和明确不做的 3 个功能分别是什么？
上午 · 学Lighthouse 怎么看；图片格式与懒加载；字体加载
下午 · 做把首页的 Lighthouse 性能分跑到 90 以上
晚上 · 验收
哪一项改动让分数提高得最多？
上午 · 学页面标题、描述、Open Graph 分享图；sitemap
下午 · 做给每个页面配好分享卡片；让测试小游戏的结果页生成专属分享图
晚上 · 验收
把网址发到聊天软件里，预览卡片好看吗？
第 12 周
上午 · 学限流、输入长度限制、防机器人提交的思路；错误页面
下午 · 做给提问箱和文案助手加限流；做好 404 和 500 页面
晚上 · 验收
有人用脚本每秒提交 100 条提问，现在会怎样？
上午 · 学数据库备份与恢复；Vercel 日志；错误监控
下午 · 做做一次备份恢复演练；故意制造一个错误，在日志里找到它
晚上 · 验收
线上出错时，你第一步去哪里看？
上午 · 学域名与 DNS 记录（A、CNAME）；HTTPS
下午 · 做绑定你的域名（还没有的话先选一个买下），确认所有页面都走 HTTPS
晚上 · 验收
你打开网站时，DNS 解析起了什么作用？
上午 · 学全项目跑一次 /code-review
下午 · 做修完所有高优先级问题，补上缺的测试
晚上 · 验收
CI 全部通过，没有未处理的高优先级问题。
上午 · 学按上线检查清单逐项过一遍
下午 · 做正式发布，把新官网放进各平台简介
晚上 · 验收
在手机、电脑、不同浏览器上各打开一遍，功能都正常。
上午 · 学写复盘：学会了什么、哪里最难、哪些部分是 Claude 替你做的
下午 · 做让 Claude 回顾代码，找出你最薄弱的 3 个知识点；决定下一步：Go 进阶、手机 App，或继续加功能
晚上 · 验收
不看代码，给朋友讲清你的网站每一层是怎么工作的。
阶段毕业标准
一个真实在线、每一层你都讲得清的产品，外加一路上的 6 个作品。接外包或找工作时，这就是你的作品集。
资源
毕业之后 · 可选
有了全栈基础再学 Go 会快很多。适合想往后端方向深入，或者想把服务跑在自己服务器上的时候。学到这里时回来找我，我再把它细化到每一天。
第 13 周
Go 语法
A Tour of Go + Go by Example。你已经会编程，重点看 Go 和 TypeScript 不一样的地方：指针、接口、错误处理、goroutine。
第 14 周
用 Go 重写一个服务
把点击统计单独拆出来，用 Go 标准库 net/http + PostgreSQL 重写，配上测试。
第 15 周
部署到自己的服务器
Docker 打包，部署到你那台新加坡 EC2，用 Caddy 配 HTTPS，和 Vercel 上的官网对接。
提示词模板
把【】里的内容换成你自己的，直接复制到 Claude Code。
学新概念
「我在学【概念】。请先用一个生活比喻解释，再给一个 10 行以内的例子，最后出 3 道由易到难的练习题。先不要给答案。」
卡住了
「这是我的代码和完整报错。先别改代码：告诉我这条报错是什么意思、可能的原因有哪些，再给我一个提示让我自己修。」
代码审查
「审查我写的这段代码，列出 bug、安全问题和可以写得更好的地方，按严重程度排序。每条说明原因，由我决定改不改。」
从需求到方案
「我要做【功能】。先不要写代码，列出要改哪些文件、数据库怎么变、页面怎么设计、要写哪些测试。等我确认后再动手。」
每日复盘
「总结这次会话里我学到的 5 个知识点，指出我今天最常犯的一类错误，再出 3 道明天复习用的题。」
Claude Code 七条规矩
/init 生成，再补上“我是初学者，每一步都请解释原因”。Claude 每次都会先读它。git commit。改坏了随时退回上一步，不用害怕试错。npm run build、npm test，再在手机上亲手点一遍。Claude 说“完成了”不等于真的能用。.env，并把 .env 加进 .gitignore。上午 · 学
下午 · 做
晚上 · 验收
--version 确认每一个都装好了。pwd、ls、cd、mkdir、touch、cat、mv、rm、grep、which 完成建文件夹、建文件、改名、搜索、删除。code . 在 VS Code 里打开一个文件夹，保存文件时自动格式化。欢迎来到第一天。接下来 72 天，你会从零做出「三岁的东哥」的正式官网，带后台、带数据库、带 AI 文案助手。开始之前，先弄清楚一个网站由哪几块组成，这样你以后每学一样东西，都知道它放在哪一层。
用餐厅打比方最好懂。
举一个课程后面会真的做出来的例子：粉丝在官网的“提问箱”里写下“街头那套 Baggy 裤是什么牌子？”，点“提交”。
课程的顺序也是照这个来的：DAY 04 到 DAY 36 主要学前端，DAY 37 起学后端和数据库，最后把它们接成一个完整的网站。今天先把“开工的工具”准备好。
平时你用鼠标点图标、拖文件，这叫图形界面。程序员还常用另一种方式：在一个黑色或白色的窗口里打字，告诉电脑做什么。这个窗口叫终端（Terminal）。为什么要学它？因为后面几乎所有开发工具，比如 Git、Node.js、Claude Code，都是在终端里运行的。打字虽然一开始慢，但能做的事比鼠标多，而且每一步都能被准确地复制和重复。
打开方法：按 Command + 空格 打开“聚焦搜索”，输入“终端”或 Terminal，回车。你会看到一行类似这样的文字：
dong@MacBook ~ %这一行叫提示符，意思是“我准备好了，请输入命令”。拆开看：
dong 是你的 Mac 用户名，MacBook 是电脑名，你的会不一样。~（波浪号）表示你现在所在的位置是“个人文件夹”，也就是 /Users/dong。% 是 zsh 这个终端程序的结尾符号。后面课件里给出的命令都不带这个符号，你只需要复制命令本身。一条命令的结构通常是：命令 选项 参数，中间用空格隔开。比如 ls -l drafts：ls 是命令（列出文件），-l 是选项（用详细格式），drafts 是参数（要列的文件夹）。输完按回车，命令才会执行。
还要认识路径，也就是文件的“地址”。Mac 上所有文件都长在一棵树上，树根写作 /。
/Users/dong/code/learn，在哪里用都指向同一个地方。~ 是个人文件夹的简写，所以 ~/code/learn 和上面那条是同一个地方。. 表示当前文件夹，.. 表示上一层文件夹。clear。下面这十个命令，今天下午你会每个都敲很多遍。先逐个看懂它们做什么、正常输出长什么样。
| 命令 | 英文来源 | 做什么 |
|---|---|---|
pwd | print working directory | 显示我现在在哪个文件夹 |
ls | list | 列出当前文件夹里有什么 |
cd | change directory | 进入另一个文件夹 |
mkdir | make directory | 新建文件夹 |
touch | touch | 新建一个空文件 |
cat | concatenate | 把文件内容显示出来 |
mv | move | 移动或改名 |
rm | remove | 删除 |
grep | global regular expression print | 在文件里搜索一段文字 |
which | which | 查某个命令的程序装在哪里 |
看一组连续的例子。假设你在个人文件夹里：
pwd
mkdir -p ~/code/learn
cd ~/code/learn
touch worlds.txt
ls逐行解释：
pwd 输出 /Users/dong，告诉你现在在个人文件夹。mkdir -p ~/code/learn 新建文件夹。-p 的意思是“中间缺哪层就一起建”，所以 code 不存在时会先建 code 再建 learn。成功时没有任何输出。终端的习惯是：没消息就是好消息。cd ~/code/learn 进入这个文件夹。成功时也没有输出，但提示符里的位置会变成 learn。touch worlds.txt 建一个空文件。ls 列出文件，你会看到 worlds.txt。文件是空的，怎么写入文字？用 echo（原样输出一句话）加上箭头符号：
echo "绅士：斯诺克，马甲衬衫皮鞋，给人安全感" > worlds.txt
echo "街头：BMX 和滑板，Baggy 裤、Vans、Oversize，给人心动" >> worlds.txt
echo "泰风：泰拳和泰国元素，泰拳短裤，给人被保护感" >> worlds.txt
cat worlds.txt> 表示“把输出写进文件，覆盖原来的内容”。>> 表示“追加到文件末尾”，原来的内容保留。cat worlds.txt 会把三行都显示出来。搜索和改名：
grep "心动" worlds.txt
mv worlds.txt three-worlds.txt
lsgrep "心动" worlds.txt 只输出包含“心动”的那一行，也就是街头那行。找不到时什么都不输出。mv 旧名字 新名字 就是改名。如果第二个参数是一个已存在的文件夹，比如 mv three-worlds.txt drafts/，就是把文件移进去。删除：rm 文件名 删除文件，rm -r 文件夹名 删除文件夹和里面的所有东西。
rm 删掉的东西不进废纸篓，没有撤销。敲回车前再看一眼文件名。永远不要照抄网上带 rm -rf / 或 sudo rm 的命令。最后是 which。装好 Node.js 以后，输入 which node，它会告诉你 node 这个程序放在哪里，比如 /opt/homebrew/bin/node。当你怀疑“是不是没装上”或者“是不是装了两个版本”时，第一步就用它查。
手机装 App 去应用商店。开发工具很多不在 App Store 里，程序员用包管理器来装。Mac 上最常用的包管理器叫 Homebrew。装好它以后，装任何工具只要一行 brew install 名字，升级、卸载也都是一行命令。
安装命令来自 Homebrew 官网 brew.sh 首页：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"这一行看着吓人，拆开其实很简单：curl 从网上下载官方的安装脚本，/bin/bash -c 运行这个脚本。安装过程中会发生这几件事：
Password:，要你输入开机密码。输入时屏幕上不显示任何字符，也没有星号，这是正常的保护措施。输完直接回车。Press RETURN/ENTER to continue，按回车继续。Installation successful! 和一段 Next steps。Next steps 很重要。在 M 系列芯片的 Mac 上，Homebrew 装在 /opt/homebrew，终端默认不知道去那里找 brew。Next steps 里会给你两三行命令，作用是把这个位置写进一个叫 ~/.zprofile 的配置文件，终端每次打开都会读它。这个“去哪些地方找命令”的清单叫 PATH。命令通常长这样，但请以你屏幕上显示的为准，直接复制屏幕上的：
echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"前两行把设置追加进 ~/.zprofile，第三行让当前这个终端窗口马上生效。之后输入 brew --version，看到 Homebrew 加一串版本号，就成功了。
Node.js 让 JavaScript 可以脱离浏览器，在你的电脑或服务器上运行。你暂时不会直接写 Node.js 程序，但后面用的 Vite、React、Next.js 这些工具都要靠它运行。装 Node.js 时会顺带装上 npm，它是 JavaScript 世界的包管理器，DAY 23 会细讲。
Node.js 有两种版本：LTS（长期支持版，稳定，适合正式项目）和 Current（最新版，功能最新）。Homebrew 的 node 装的是最新版，一般领先 LTS 一个大版本。本课程用到的工具在两者上都能正常运行，你直接用 Homebrew 装就行。以后如果某个项目明确要求 LTS，再去 nodejs.org 下载 LTS 安装包即可。
Git 是版本管理工具。它像一台给代码拍照的相机，每拍一张就记下“这时候文件长什么样”，改坏了随时能退回去。明天整天都学它。Mac 自带一个苹果版的 Git，我们用 Homebrew 再装一个更新的版本。
brew install node git一条命令同时装两个工具。它会输出很多 ==> Downloading 和 ==> Pouring 的行，表示正在下载、解压。结束后验证：
node -v
npm -v
git --version
which git正常输出大致是这样（数字以你看到的为准）：
v24.x.x
11.x.x
git version 2.x.x
/opt/homebrew/bin/git最后一行很关键：which git 显示 /opt/homebrew/bin/git，说明你用的是 Homebrew 装的新版；如果显示 /usr/bin/git，说明还在用苹果自带的旧版，一般是 PATH 没设好，回到上一节检查 Next steps。老款 Intel 芯片的 Mac 会显示 /usr/local/bin/git，也是对的。
写代码可以用任何文本编辑器，但专门的代码编辑器会给代码上色、自动补全、提示错误。VS Code 是微软出的免费编辑器，也是现在最多人用的。去官网 code.visualstudio.com 下载 Mac 版，解压后把 Visual Studio Code 拖进“应用程序”文件夹。
接着装三个插件（扩展，Extensions），它们像给编辑器加装的配件：
装插件的方法：点左侧栏四个小方块的图标（或按 Command + Shift + X），在搜索框里输入名字，认准发布者（语言包和 ESLint 是 Microsoft，Prettier 是 Prettier），点“Install”。
还有一个很实用的设置：让终端里能用 code 命令打开文件夹。在 VS Code 里按 Command + Shift + P 打开命令面板，输入 shell command，选择 Shell Command: Install 'code' command in PATH。之后在终端里进入任何文件夹，输入 code .（注意有个点，表示当前文件夹），VS Code 就会打开它。
这门课前 24 天，Claude 的角色是“老师”：只讲解、出题、给提示，代码全部由你自己敲。原因很简单：让别人替你写，你看懂了，但下次还是不会写。自己敲过、错过、改过，才真的会。
Claude Code 有一个叫输出风格（output style）的设置，决定它怎么和你合作。其中 Learning 风格会在讲解时加上“为什么这样做”的小结，并且在遇到值得练习的代码时停下来，在文件里留一个 TODO(human) 标记，请你自己写那几行，写完再告诉它。这和我们的学习方式很合拍。
切换方法：在 Claude Code 的输入框里输入 /output-style，它会列出可选的风格，选择 Learning；也可以直接输入 /output-style learning。切换后，从你的下一条消息开始生效。
如果你用的桌面 App 不认这个命令，可以改设置文件：在终端运行 code ~/.claude/settings.json，在最外层的大括号里加上 "outputStyle": "Learning" 这一项，保存。注意 Learning 首字母大写，写错大小写会变回默认风格。不同版本的入口可能变化，以 Claude Code 文档为准：https://code.claude.com/docs 。
~/.claude/settings.json
{
"outputStyle": "Learning"
}这是文件里只有这一项时的样子。如果文件里已经有别的设置，就在其他项后面加一个英文逗号，再加这一行。JSON 格式要求每两项之间用逗号隔开，最后一项后面不能有逗号。
打开终端，认识自己的位置
按 Command + 空格，输入“终端”，回车。依次输入下面三条命令，每条按一次回车：
pwd
ls
ls -lapwd 输出 /Users/你的用户名。ls 列出 Desktop、Documents、Downloads 等文件夹。ls -la 多显示了以点开头的隐藏文件，比如 .zprofile，还有每个文件的大小和修改时间。
ls 的输出里找到 Desktop，并且知道提示符里的 ~ 指的就是 pwd 显示的那个位置。安装 Homebrew
复制下面这行，粘贴到终端，回车。按提示输入开机密码（屏幕不显示，输完回车），再按一次回车确认。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"等到出现 Installation successful!，往上翻找到 Next steps，把那里给出的两三行命令逐行复制运行。然后验证：
brew --version
which brewHomebrew 和版本号；第二行显示 /opt/homebrew/bin/brew（Intel 芯片的 Mac 是 /usr/local/bin/brew）。如果提示 command not found: brew，看下面“常见坑”第一条。安装 Node.js 和 Git
brew install node git等它跑完（几分钟），再运行：
node -v
npm -v
git --version
which node
which gitcommand not found；which git 显示的路径里有 homebrew。安装 VS Code 和三个插件
浏览器打开 https://code.visualstudio.com/ ，下载 Mac 版，把应用拖进“应用程序”。第一次打开时 Mac 可能问“是否确定要打开”，点“打开”。
按 Command + Shift + X 打开扩展面板，依次搜索并安装：Chinese (Simplified)、Prettier - Code formatter、ESLint。装完语言包后点右下角的重启按钮。
然后按 Command + , 打开设置：
format on save，勾选“Editor: Format On Save”（保存时格式化）。default formatter，在“Editor: Default Formatter”里选 Prettier - Code formatter。最后按 Command + Shift + P，输入 shell command，选择 Shell Command: Install 'code' command in PATH。回到终端验证：
which codewhich code 输出一个路径，而不是 code not found。建好学习根目录
整门课的代码都放在 ~/code 下面，前两天的练习放在 ~/code/learn。
mkdir -p ~/code/learn
cd ~/code/learn
pwdpwd 输出 /Users/你的用户名/code/learn，提示符里也显示 learn。新建文件并写入内容
touch worlds.txt
ls
echo "绅士：斯诺克，马甲衬衫皮鞋，给人安全感" > worlds.txt
echo "街头：BMX 和滑板，Baggy 裤、Vans、Oversize，给人心动" >> worlds.txt
echo "泰风：泰拳和泰国元素，泰拳短裤，给人被保护感" >> worlds.txt
cat worlds.txt注意 echo 后面的引号必须是英文引号 "，不是中文的“”。输入法切到英文再打引号。
cat 显示三行，顺序是绅士、街头、泰风。再试一次把第一条的 > 换成 >> 会怎样？想清楚再动手。建文件夹、改名、移动
mkdir drafts
mv worlds.txt three-worlds.txt
mv three-worlds.txt drafts/
ls
ls drafts
cat drafts/three-worlds.txt第一个 mv 是改名，第二个 mv 是移动，因为 drafts/ 是一个已存在的文件夹。
ls 只剩 drafts；ls drafts 显示 three-worlds.txt；cat 仍然显示三行内容。用 cd 在文件夹之间来回走
cd drafts
pwd
cd ..
pwd
cd ~
pwd
cd ~/code/learncd .. 回到上一层，cd ~ 回到个人文件夹，最后一行回到 learn。每一步都用 pwd 确认自己在哪。
pwd 分别以 /learn/drafts、/learn、你的用户名结尾。搜索和查找：grep 与 which
grep "心动" drafts/three-worlds.txt
grep -n "泰" drafts/three-worlds.txt
grep "滑板鞋" drafts/three-worlds.txt
which nodegrep -n 会在结果前面加上行号。第三条找不到，所以什么都不输出，这不是出错。
3:泰风：……；第三条没有输出；第四条输出 node 的路径。删除：rm 和 rm -r
touch trash.txt
mkdir old
ls
rm trash.txt
rm -r old
lsls 里 trash.txt 和 old 都不见了，只剩 drafts。去废纸篓看看，那里也没有它们。用 VS Code 打开文件夹
code .VS Code 打开后，左侧能看到 drafts/three-worlds.txt。点开它，在最后加一行“今天装好了开发环境”，按 Command + S 保存。回到终端：
cat drafts/three-worlds.txt在 Claude Code 里切到 Learning 风格
打开 Claude Code，新建一个会话，工作文件夹选 ~/code/learn。在输入框输入：
/output-style在列表里选 Learning。如果桌面 App 不支持这个命令，按上午第 7 节的方法在 ~/.claude/settings.json 里加上 "outputStyle": "Learning"，然后新开一个会话。切好后发一句：“我今天学了 10 个终端命令，请出 3 道题考我，不要直接给答案。”
drafts 会成为第一批被“拍照”的文件。/opt/homebrew/bin 找程序。往上翻找到那几行复制运行；翻不到了就运行上午第 4 节给出的三行，然后关掉终端重新打开。Sorry, try again，再输一次即可。cat "my notes.txt"，或者干脆养成习惯：文件名只用小写英文、数字和短横线。不看笔记，在终端新建文件夹 day1，进去建 hello.txt，写入一句话，再把内容显示出来。
cd ~/code/learn
mkdir day1
cd day1
touch hello.txt
echo "今天装好了开发环境，明天学 Git。" > hello.txt
cat hello.txttouch 这一步可以省略，因为 > 在文件不存在时会自动创建它。最后一行应该输出你写的那句话。做完用 pwd 确认自己在 day1 里。
粉丝在官网上点了“只看街头”的按钮，页面上只剩下街头的穿搭。这个过程里，前端、后端、数据库可能各做了什么？
前端显示按钮，接收你的点击，并把结果画到页面上。如果穿搭数据存在服务器上，前端会向后端请求“街头世界的穿搭”；后端收到请求，去数据库里查出 world 是 street 的那些 look，整理好返回给前端。数据库负责把所有穿搭长期存着，并按条件查出来。如果数据已经全部在页面里，也可以只靠前端筛选，不需要后端参与，这正是后面课程里会遇到的设计选择。
你输入 which git，看到 /usr/bin/git。这说明什么？怎么处理？
说明终端用的是苹果自带的 Git，而不是 Homebrew 装的新版。通常是因为 PATH 没设好，终端没有先去 /opt/homebrew/bin 找。先运行 brew --version 确认 Homebrew 可用，再检查 ~/.zprofile 里有没有 brew shellenv 那一行（可以用 cat ~/.zprofile 查看），没有就补上，重开终端后再运行 which git。
git add 和 git commit 的区别。git init、git status、git add、git commit、git log、git diff 管理 learn 文件夹，完成至少 5 次提交。git restore 把它恢复原样。git switch -c 开分支、切回 main 并合并。gh auth login 在终端登录，把 learn 推到 GitHub 并在网页上看到提交记录。昨天你在 ~/code/learn 里建了文件、改了名、删了东西。想象一下：你花一下午写好了链接主页，晚上又改了一通，结果页面乱了，却想不起来改了哪几行。没有备份，只能凭记忆一点点改回去。
很多人的土办法是复制一份文件夹，起名“官网-最终版”“官网-最终版2”“官网-真的最终版”。文件夹越来越多，谁也说不清每一份改了什么。
版本管理就是专门解决这个问题的。它像游戏里的存档点：每到一个满意的状态就存一次档，并写一句说明“这次改了什么”。以后随时能查看任何一次存档，能比较两次存档的差别，也能退回任何一次存档。Git 是现在几乎所有程序员都在用的版本管理工具，你昨天已经用 Homebrew 装好了。
Pro Git 第 1 章讲到一个关键点：Git 保存的不是“改了哪几行”的清单，而是每次存档时整个项目的快照，就像给整个文件夹拍一张照片。没变的文件，Git 不会重复存，只记一个“和上次一样”。所以存档很快，也很省空间。
另外，Git 是分布式的：你电脑上就有完整的历史记录，断网也能存档、查历史。GitHub 是一个放 Git 仓库的网站，相当于云端的备份和展示柜。Git 和 GitHub 是两回事：Git 是工具，GitHub 是网站。
这是今天最重要的概念，也是晚上验收的原题。用拍合照打比方：
git add 文件名 就是叫某个人站到镜头前。没被叫到的人即使在现场，也不会被拍进去。git commit 就是按下快门，把暂存区里的所有东西拍成一张照片，存进相册，并在背面写上一句说明。为什么不直接拍，还要多一个暂存区？因为你经常同时改了好几件事。比如你改了链接主页的颜色，又顺手写了一半的新表单。颜色改好了想存档，表单还没写完不想存。有暂存区，你就可以只 git add 颜色相关的文件，提交一次“调整按钮颜色”，表单留到写完再提交。每一次提交只做一件事，以后查历史就很清楚。
所以一个文件在 Git 眼里有几种状态：
| 状态 | 意思 | git status 里的说法 |
|---|---|---|
| 未跟踪 | 新文件，Git 还不认识它 | Untracked files |
| 已修改 | 改过了，但还没放进暂存区 | Changes not staged for commit |
| 已暂存 | 已经 add，等着下次 commit | Changes to be committed |
| 已提交 | 已经存进仓库，和最新存档一样 | nothing to commit, working tree clean |
git add 是“选这次要存哪些改动”，git commit 是“真正存档，并写下说明”。只 add 不 commit，存档不会产生；没 add 就 commit，Git 会说没东西可提交。每次提交，Git 都会记下“是谁提交的”。所以第一次用之前要告诉它你的名字和邮箱。这几条命令只需要运行一次，--global 表示对这台电脑上的所有仓库生效。
git config --global user.name "Dong"
git config --global user.email "你的邮箱@example.com"
git config --global init.defaultBranch main
git config --global core.editor "code --wait"noreply 邮箱替换它。main。不设的话，旧版 Git 会叫 master，和 GitHub 的默认不一致。检查配置：运行 git config --global --list，会列出你刚设的这几项。
下面用 learn 文件夹走一遍完整流程，每条命令后面是它正常的输出。
git init：把当前文件夹变成 Git 仓库。
cd ~/code/learn
git initInitialized empty Git repository in /Users/dong/code/learn/.git/它在文件夹里建了一个隐藏的 .git 文件夹，所有存档都放在那里。你的文件本身一点没变。不要手动去改 .git 里的东西。
git status：查看当前状态。这是你最该常敲的命令，每做一步都可以看一眼。
On branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
day1/
drafts/
nothing added to commit but untracked files present (use "git add" to track)逐行读：现在在 main 分支；还没有任何提交；有两个未跟踪的文件夹；最后一行说“没有东西放进暂存区，但有未跟踪的文件，可以用 git add 跟踪它们”。Git 的提示信息都很友好，括号里往往直接告诉你下一步该敲什么。
git add：把改动放进暂存区。
git add drafts/three-worlds.txt
git add .第一行只添加一个文件。第二行的 . 表示“当前文件夹里的所有改动”。刚开始用 git add . 没问题，但每次之前先 git status 看清楚会加进去哪些东西。
git commit：存档。
git commit -m "加入 DAY 01 的终端练习文件"[main (root-commit) 3f2a9c1] 加入 DAY 01 的终端练习文件
2 files changed, 5 insertions(+)
create mode 100644 day1/hello.txt
create mode 100644 drafts/three-worlds.txt-m 后面是这次提交的说明。输出里的 3f2a9c1 是这次提交的编号（完整编号很长，这里显示前 7 位），你看到的会不一样。root-commit 表示这是第一次提交。下面两行统计了改了几个文件、加了几行。
提交说明怎么写？原则和你写视频文案一样：说事情，具体，不绕弯。好的说明让三个月后的你一眼看懂这次改了什么，比如“链接主页加上 Instagram 按钮”“修正泰风卡片的颜色”。不好的说明是“改了一下”“更新”“123”，等你真要找某次改动时，它们毫无帮助。一次提交只做一件事，说明就很好写；如果一句话说不清，多半是这次塞了太多改动，应该拆成几次提交。
! 有特殊含义（调出历史命令），放在双引号里也可能让命令报 event not found。提交说明和 echo 的内容里先不要用英文感叹号，用句号就好。git log：查看历史。
git log --oneline7b1d0e4 (HEAD -> main) 写下 add 和 commit 的区别
a92c3f8 添加 README
3f2a9c1 加入 DAY 01 的终端练习文件--oneline 让每次提交只占一行，最新的在最上面。HEAD -> main 表示“你现在就在这里”。不加 --oneline 会显示作者、时间等完整信息，内容多时会进入翻页模式，按空格翻页，按 q 退出。
git diff：看工作区里改了什么，还没 add 的那部分。
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -1 +1,2 @@
# 东哥的学习仓库
+这里放 DAY 01 到 DAY 04 的练习。以 + 开头的行是新加的，以 - 开头的行是删掉的，没有符号的是没变的上下文。@@ -1 +1,2 @@ 表示“原来第 1 行这一段，现在变成了从第 1 行开始的 2 行”。
Git 最让人安心的地方，是改坏了能恢复。git restore 有两种用法，对应两种后悔：
git restore 文件名：把工作区里这个文件恢复成暂存区（没 add 过就是最近一次提交）里的样子。相当于“我刚才改的全不要了”。git restore --staged 文件名：把文件从暂存区里拿出来，但保留你的修改。相当于“这个人先别拍进照片，但让他留在现场”。所以如果你已经 git add 了一个改坏的文件，要恢复就分两步：先 git restore --staged 拿出暂存区，再 git restore 丢掉修改。
git restore 文件名 丢掉的改动，是从来没被提交过的，Git 也找不回来。用之前先 git diff 看一眼，确认这些改动真的不要了。另外它只对 Git 已经跟踪的文件有效，从没提交过的新文件改坏了，它救不了。这也是“经常提交”的理由。Pro Git 第 3 章讲分支，今天只需要理解它是什么。分支就像一个平行世界。你在 main 上有一个能用的版本。想试一个大胆的改动，比如把整页换成街头风，又怕改砸了影响能用的版本，就开一个分支，在分支上随便改、随便提交。改好了，把分支合并回 main；改砸了，直接扔掉这个分支，main 毫发无损。
技术上，分支只是一个指向某次提交的“书签”。HEAD 是另一个书签，表示“你现在在哪个分支上”。常用命令：
git branch
git switch -c try-street
git switch main
git merge try-street
git branch -d try-streetgit branch：列出所有分支，前面带 * 的是当前分支。git switch -c try-street：新建一个叫 try-street 的分支并切过去。-c 是 create。git switch main：切回 main。切换时，工作区里的文件会变成那个分支的样子。git merge try-street：在 main 上运行，把 try-street 的提交合并进来。git branch -d try-street：合并完了，删掉这个书签。提交记录不会丢，已经在 main 上了。DAY 53 开始，你改每个功能都会走“开分支、提交、合并”的流程。今天下午做一次小演示就够了。
到目前为止，所有存档都在你的电脑上。电脑坏了，存档也没了。远程仓库就是放在网上的一份副本。GitHub 是最大的远程仓库网站，DAY 03 的 Vercel 也是从 GitHub 读取你的代码来发布网站的。
几个新词：
origin。推送代码需要证明“你是你”。GitHub 早就不接受在终端直接输入账号密码了，要用令牌或 SSH 密钥，手动配置对新手很麻烦。所以我们用 GitHub 官方的命令行工具 GitHub CLI，命令叫 gh。运行 gh auth login，它会带你在浏览器里完成登录，然后自动帮 Git 配好凭据，之后 git push 不用再输密码。
gh auth login 会依次问几个问题（不同版本措辞略有差别），用方向键选择，回车确认：
? Where do you use GitHub? GitHub.com
? What is your preferred protocol for Git operations on this host? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser
! First copy your one-time code: 1A2B-3C4D
Press Enter to open https://github.com/login/device in your browser...回到终端，看到 Authentication complete 和 Logged in as 你的用户名 就成功了。登录令牌会存进 Mac 的钥匙串，不会以明文出现在文件里。
最后是 .gitignore：一个告诉 Git “这些文件别管”的清单。Mac 的 Finder 会在文件夹里偷偷生成 .DS_Store 文件，记录图标位置之类的信息，它对项目毫无用处，应该让 Git 忽略。以后 node_modules、存密钥的 .env 也都会写进这个清单。
配置 Git 的名字、邮箱和默认设置
git config --global user.name "Dong"
git config --global user.email "你的邮箱@example.com"
git config --global init.defaultBranch main
git config --global core.editor "code --wait"
git config --global --list第 2 行换成你准备注册 GitHub 的真实邮箱。
user.name=Dong、user.email=……、init.defaultbranch=main、core.editor=code --wait。把 learn 变成仓库
cd ~/code/learn
git init
ls -la
git statusgit init 输出 Initialized empty Git repository；ls -la 里多了 .git；git status 显示 No commits yet 和昨天的 drafts/、day1/（如果你做了验收题）。第 1 次提交：.gitignore
echo ".DS_Store" > .gitignore
cat .gitignore
git status
git add .gitignore
git status
git commit -m "添加 .gitignore，忽略 .DS_Store"注意观察两次 git status 的区别：add 之前 .gitignore 在 Untracked files 里，add 之后它出现在 Changes to be committed 下面，这就是暂存区。
root-commit 和你写的说明。第 2 次提交：昨天的练习文件
git add .
git status
git commit -m "加入 DAY 01 的终端练习文件"
git statusgit status 显示 nothing to commit, working tree clean，意思是工作区和最新存档完全一样。第 3 次提交：README，并学会看 diff
echo "# 东哥的学习仓库" > README.md
git add README.md
git commit -m "添加 README"
code README.md在 VS Code 里给 README.md 加第二行：这里放 DAY 01 到 DAY 04 的练习。保存。回到终端：
git status
git diff
git add README.md
git commit -m "README 写明仓库用途"git diff 里看到以 + 开头的那一行新内容。VS Code 左侧文件名旁边也会出现一个 M（Modified，已修改）标记，提交后消失。第 4 次提交：写下今天最重要的笔记
新建 git-notes.md，用你自己的话写三行：工作区是什么、暂存区是什么、仓库是什么。
code git-notes.md写好保存后：
git add git-notes.md
git commit -m "写下工作区、暂存区、仓库的笔记"
git log --onelinegit log --oneline 显示 4 行，最新的在最上面，旁边有 (HEAD -> main)。故意改坏，再恢复
情况一，改坏了还没 add：
echo "乱写的一行" > drafts/three-worlds.txt
cat drafts/three-worlds.txt
git diff
git restore drafts/three-worlds.txt
cat drafts/three-worlds.txt情况二，改坏了而且已经 add：
echo "又乱写了" > drafts/three-worlds.txt
git add drafts/three-worlds.txt
git restore --staged drafts/three-worlds.txt
git restore drafts/three-worlds.txt
cat drafts/three-worlds.txt
git statuscat 都显示原来的三个世界（和你昨天加的那一行）；最后的 git status 是 working tree clean。第 5 次提交：在分支上试一试
git switch -c try-street
echo "街头补充：周末去滑板场，拍一条 BMX 的日常" >> drafts/three-worlds.txt
git add drafts/three-worlds.txt
git commit -m "在分支上补充街头的内容"
git switch main
cat drafts/three-worlds.txt切回 main 后，刚加的那行不见了。别慌，它在 try-street 分支上。现在把它合并进来：
git merge try-street
cat drafts/three-worlds.txt
git branch -d try-street
git log --onelineFast-forward，意思是 main 直接往前挪到了分支的位置；合并后那一行回来了；git log --oneline 显示 5 次提交。注册 GitHub 账号
浏览器打开 https://github.com/ ，点 Sign up，按页面提示用邮箱注册。这一步需要你自己完成。用户名想好再定，它会出现在你所有仓库的网址里，比如 github.com/用户名/learn。注册后按提示验证邮箱，并开启两步验证（Two-factor authentication），GitHub 会引导你设置。
安装 GitHub CLI 并登录
brew install gh
gh auth login按上午第 7 节的说明依次选择：GitHub.com、HTTPS、Yes、Login with a web browser。复制终端里的一次性验证码，按回车打开浏览器，粘贴验证码，点授权。
gh auth statusgh auth status 显示 Logged in to github.com account 你的用户名。在 GitHub 上建仓库并推送
cd ~/code/learn
gh repo create learn --private --source=. --remote=origin
git remote -v
git push -u origin maingh repo create learn：在你的 GitHub 账号下建一个叫 learn 的仓库。--private：私有仓库，只有你能看到。想公开就换成 --public，以后也能在网页上改。--source=.：把当前文件夹和它关联起来。--remote=origin：在通讯录里把它记为 origin。git remote -v：列出远程仓库，会看到两行 origin，分别用于拉取（fetch）和推送（push）。git push -u origin main：把 main 分支推到 origin。-u 记住这个对应关系，以后直接 git push 就行。* [new branch] main -> main 和 branch 'main' set up to track 'origin/main'。在网页上查看，再推一次
gh repo view --web浏览器会打开这个仓库。你能看到 README 的内容显示在文件列表下方，点 “5 commits”（或时钟图标）能看到每次提交的说明。然后回到终端，给 git-notes.md 加一行“git push 把本地提交送到 GitHub”，再：
git add git-notes.md
git commit -m "补充 push 的笔记"
git pushgit log --oneline 可以少遇到。core.editor，VS Code 会打开一个 COMMIT_EDITMSG 文件。在第一行写提交说明，保存，关掉这个标签页，提交就完成了。如果没设置而进了 Vim，按 Esc，输入 :q! 回车退出，再用 -m 重新提交。pwd 看看自己在哪，cd ~/code/learn 回去。git remote -v 看看 origin 指向哪里；如果已经指向你的 learn 仓库，直接 git push -u origin main 即可。讲清 git add 和 git commit 的区别；故意改坏一个文件，再用 Git 恢复它。
git add 把工作区里的改动放进暂存区，意思是“选好这次要存档的内容”，它不产生存档。git commit 把暂存区里的内容拍成一个快照存进仓库，并附上说明，这才是真正的存档，以后能在 git log 里看到、能恢复。两步分开，是为了让你能挑选改动，每次提交只做一件事。
演示：
echo "改坏了" > README.md
git diff
git restore README.md
cat README.md如果已经 add 过，先 git restore --staged README.md，再 git restore README.md。
下面是一段 git status 的输出。about.txt 和 README.md 分别处在什么状态？如果运行 git commit -m "更新"，哪个会被存档？
Changes to be committed:
modified: README.md
Changes not staged for commit:
modified: about.txtREADME.md 已暂存，about.txt 已修改但未暂存。运行 commit 只会存档 README.md 的改动，about.txt 的改动留在工作区。想一起存，要先 git add about.txt。
用自己的话解释 git push -u origin main 里每一部分的意思。为什么我们用 gh auth login 登录，而不是在终端里输 GitHub 密码？
push 是推送；origin 是远程仓库的名字；main 是要推的分支；-u 记住本地 main 对应远程的 origin/main，以后直接 git push 即可。GitHub 已经不接受在命令行用账号密码推送，需要令牌或 SSH 密钥。gh auth login 通过浏览器完成授权，自动把凭据存进钥匙串并配置给 Git，省去手动管理令牌，也避免把密码到处输入。
--staged 等选项的准确含义gh auth login 和 gh repo create 的所有选项curl -I 亲眼看到它们。git push 之后网站会自动更新。前两天你装好了工具，学会了用 Git 存档并推到 GitHub。今天是第一个上线日：把桌面上那份旧官网变成一个任何人都能打开的网址。
先做个小实验。在终端运行 open ~/Desktop/dongge-site/index.html，浏览器会打开官网，地址栏显示的是 file:///Users/dong/Desktop/dongge-site/index.html。file:// 的意思是“这是本机上的一个文件”。这个地址发给朋友是打不开的，因为文件在你的硬盘里，别人的手机碰不到你的硬盘。
要让别人打开，需要把文件放到一台一直开机、连着网、有固定地址的电脑上，这台电脑叫服务器。别人的浏览器向服务器要文件，服务器把文件发过去。今天上午就来弄清楚这个“要”和“发”的过程，下午用 Vercel 把它做出来。
deploy.sh 和 nginx-dongge.conf 是以前准备给自己的云服务器用的：前者负责把文件上传到服务器，后者是服务器上网页软件 nginx 的配置。这次我们用 Vercel，不需要自己管服务器，所以这两个文件先不用，保留在文件夹里即可。网络上每台服务器都有一个数字地址，叫 IP 地址，长得像 76.76.21.21。数字难记，所以人们给它起名字，这就是域名，比如 vercel.com，或者今天你会得到的 dongge-site.vercel.app。
域名从右往左读，层级越来越具体。以 dongge-site.vercel.app 为例：最右边的 app 是顶级域名，和 .com、.cn 是一类；vercel.app 是 Vercel 公司买下的域名；最左边的 dongge-site 是 Vercel 分给你的子域名。所以今天得到的网址是“借住”在 Vercel 的域名下面，免费但带着 vercel 的字样。DAY 69 你会绑定一个完全属于自己的域名。
浏览器只认 IP，不认名字。把域名翻译成 IP 的系统叫 DNS（Domain Name System，域名系统）。它就像手机通讯录：你点“东哥”，手机替你拨出那串号码。你在浏览器里输入域名，浏览器先去问 DNS：“这个名字对应哪个 IP？”拿到 IP 才能出发。
DNS 的答案会被层层缓存（你的电脑、路由器、网络运营商都会记一段时间），所以第二次访问同一个网站会更快。这也是为什么以后你改了域名设置，有时要等一会儿才生效。
在终端里可以亲自查一次 DNS：
dig +short vercel.comdig 是 Mac 自带的 DNS 查询工具，+short 表示只显示结果。输出是一到几个 IP 地址，每行一个。你看到的数字和别人可能不一样，大网站会根据你所在的位置给你离得最近的服务器。
拿到 IP 后，浏览器和服务器之间用一种约定好的格式对话，叫 HTTP（超文本传输协议）。用点单打比方：
/ 表示首页，/looks/street.jpg 表示一张图）、还有一些附加信息叫请求头（比如“我是 iPhone 上的 Safari”“我能看懂中文”）。一次请求写出来其实就是几行文字。手机打开官网首页时，发出的请求大致长这样：
GET / HTTP/2
Host: dongge-site.vercel.app
User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS like Mac OS X) ...
Accept-Language: zh-CN,zh第 1 行是请求行：方法 GET，路径 /，协议版本 HTTP/2。第 2 行 Host 说明要访问哪个网站，因为一台服务器上可能住着成千上万个网站，Vercel 靠这一行分辨你要的是 dongge-site 而不是别人的。第 3 行 User-Agent 说明“我是什么设备、什么浏览器”。第 4 行说明“我优先看中文”。这些都由浏览器自动写好，你不用手动发，但要知道它们存在。
现在网站几乎都用 HTTPS，多出来的 S 是 Secure。它在对话外面套了一层加密，路上的人（比如公共 Wi-Fi 的管理者）看不到也改不了内容。浏览器地址栏的小锁图标就表示用的是 HTTPS。Vercel 会自动给你的网站配好 HTTPS，不用你操心。
用 curl 可以在终端里发一次请求，-I 表示只看响应头，不看正文：
curl -I https://vercel.comHTTP/2 200
content-type: text/html; charset=utf-8
server: Vercel
...第一行 HTTP/2 200：用的是 HTTP 第 2 版，状态码 200。content-type 说明内容是 HTML，编码是 utf-8（能正常显示中文）。server: Vercel 说明是 Vercel 的服务器回复的。实际输出会多很多行，先认识这几行就够了。
状态码是三位数字，第一位表示大类。记住下面几个就能看懂大部分情况：
| 状态码 | 意思 | 你会在哪见到 |
|---|---|---|
| 200 OK | 成功，东西在这 | 正常打开网页 |
| 301 / 308 | 永久搬家了，请去新地址 | 用 http:// 打开时，Vercel 会用 308 让你跳到 https:// |
| 304 Not Modified | 没变，用你上次缓存的就行 | 第二次打开同一个页面 |
| 404 Not Found | 没有这个东西 | 路径写错了，或文件不存在 |
| 500 Internal Server Error | 服务器自己出错了 | 以后写后端代码有 bug 时 |
规律是：2 开头表示成功，3 开头表示“去别处拿”，4 开头表示“你（浏览器这边）要的东西有问题”，5 开头表示“服务器那边出了问题”。以后排查问题时，先看状态码，就知道该往哪边找。
试试用 http 访问会怎样：
curl -I http://nextjs.orgHTTP/1.1 308 Permanent Redirect
Location: https://nextjs.org/
...308 加上 Location 这一行，意思是“请改用 https 的地址”。浏览器看到后会自动跳过去，你在地址栏里几乎察觉不到。
把前面的知识串起来。你在手机上打开 https://dongge-site.vercel.app，到页面出现，中间发生了这些事：
GET /，意思是“请给我首页”。index.html，回复 200 和 HTML 内容。looks/ 里的照片。一个页面往往不止一次请求，而是几次到几十次。下午你会在浏览器的开发者工具里亲眼看到这一串请求。这个过程就是晚上的验收题，今天要能用自己的话讲一遍。
自己租服务器上线，要装系统、装 nginx、配 HTTPS 证书、每次改完手动上传。旧官网的 deploy.sh 和 nginx-dongge.conf 就是为这一套准备的。
Vercel 是一个网站托管平台，把这些都包了：
git push 到 main 分支，GitHub 就通知 Vercel，Vercel 自动拉取最新代码，重新发布一次。每一次发布叫一个部署（Deployment）。index.html，不需要构建，所以导入时框架选 Other，构建命令留空。Vercel 的 Hobby 计划免费，适合学习和个人项目。它的条款写明 Hobby 用于个人、非商业用途，以后如果网站用于商业合作，再按官方条款决定是否升级，这由你自己判断。
最后一个小细节：Vercel 会把仓库里的所有文件都当作网站的一部分发布出去，包括 deploy.sh。现在它里面只有占位符，公开了也没关系，但更好的习惯是只发布需要的文件。Vercel 支持一个叫 .vercelignore 的文件，写法和 .gitignore 一样，列在里面的文件不会被发布。下午我们会用它把两个服务器文件和 README 排除掉。
dongge-site/.vercelignore
deploy.sh
nginx-dongge.conf
README.md每行一个文件名。这三个文件仍然留在 GitHub 仓库里，只是不会出现在网站上。
到今天为止，你手里有三个地方存着同一份代码，它们的分工要分清：
所以以后改网站的固定流程就是：本地改文件，git add，git commit，git push，然后等 Vercel 自动部署。这条流水线从今天一直用到第 72 天。
关于部署，还有三点值得现在就知道：
dongge-site.vercel.app 只是指向“当前最新的正式部署”。先认识旧官网文件夹
cd ~/Desktop/dongge-site
ls -la
ls looks
cat looks/README.txt
open index.html你会看到 index.html、looks/、README.md、deploy.sh、nginx-dongge.conf。looks/README.txt 说明了照片的固定文件名：gentleman.jpg、street.jpg、thai.jpg。没有照片时页面显示纯色图框，不影响上线。
file:// 开头。确认没有私人信息要被公开
grep -n "SERVER_\|SSH_KEY" deploy.sh输出里应该是 你的服务器IP或域名、你的密钥.pem 这类占位文字。如果你以前填过真实的服务器地址或密钥路径，先用 VS Code 改回占位文字再继续，因为这些内容会进入 GitHub。
deploy.sh 里没有真实的服务器地址。加上 .gitignore 和 .vercelignore
echo ".DS_Store" > .gitignore
printf "deploy.sh\nnginx-dongge.conf\nREADME.md\n" > .vercelignore
cat .gitignore
cat .vercelignoreprintf 和 echo 类似，但会把 \n 当成换行，所以一条命令就写出了三行。
cat .vercelignore 显示三行文件名。变成 Git 仓库并提交
git init
git add .
git status
git commit -m "旧版官网：首次纳入 Git 管理"git status 在 commit 前列出了 index.html、looks/README.txt 等文件，全部在 Changes to be committed 下面；commit 输出里有 root-commit。推到 GitHub
gh repo create dongge-site --private --source=. --remote=origin
git push -u origin main
gh repo view --web和昨天推 learn 一样。私有仓库也可以导入 Vercel。
github.com/你的用户名/dongge-site，能看到全部文件和 README 的内容。用 GitHub 账号登录 Vercel
打开 https://vercel.com/ ，点 Sign Up，选择 Continue with GitHub。计划类型选 Hobby，填一个名字。GitHub 会弹出授权页，询问是否允许 Vercel 读取你的账号信息。注册、同意条款和授权都由你自己确认完成。
导入 dongge-site 仓库
打开 https://vercel.com/new （或在控制台点 Add New… 再选 Project）。在 Import Git Repository 列表里找到 dongge-site，点旁边的 Import。
如果列表里没有它，点列表下方调整 GitHub 权限的链接，会跳到 GitHub 的 Vercel 应用设置页。在 Repository access 里选择 Only select repositories 并勾上 dongge-site（更安全，以后新项目要回来再勾），或选择 All repositories（省事）。保存后回到 Vercel 刷新。
dongge-site。选 Other，不填构建命令，部署
./，因为 index.html 就在仓库最外层。点 Deploy。静态网站很快，一般几十秒内完成，页面会显示祝贺信息和网站截图。界面文字可能随 Vercel 更新有变化，以实际页面为准。
dongge-site.vercel.app。如果这个名字被别人用了，会自动带上一段后缀，以页面显示的为准。用手机打开，再用终端验证
用手机浏览器打开你的网址，确认页面正常。然后在电脑终端运行（把网址换成你自己的）：
dig +short dongge-site.vercel.app
curl -I https://dongge-site.vercel.app
curl -I http://dongge-site.vercel.app
curl -I https://dongge-site.vercel.app/deploy.shdig 输出一到几个 IP；第一个 curl 是 HTTP/2 200 和 server: Vercel；第二个是 308 Permanent Redirect，Location 指向 https 地址；第三个是 HTTP/2 404，说明 .vercelignore 生效了，deploy.sh 没有被发布。如果第三个是 200，先检查 .vercelignore 的文件名（开头有个点）和内容，再对照 Vercel 文档的当前说明；deploy.sh 里只有占位文字，暂时公开也不影响安全。在开发者工具里看一串请求
用 Chrome 打开你的网址，按 Command + Option + I 打开开发者工具，点顶部的 Network（网络）标签，然后按 Command + R 刷新页面。列表里每一行就是一次请求。
looks/ 里还没放照片，你会看到 gentleman.jpg 这一行是 404，这正是“文件不存在”。页面照样能看，因为它为这种情况准备了纯色图框。改一行字，push，看网站自动更新
grep -n "kicker mono" index.html
code index.htmlgrep -n 告诉你这一行在第几行。在 VS Code 里按 Control + G 跳到那一行，把：
dongge-site/index.html
<p class="kicker mono">Sansui Dongge · 小红书 / TikTok / Instagram / Facebook</p>改成：
<p class="kicker mono">Sansui Dongge · 每周四、五、日更新</p>只改两个标签中间的文字，<p class="kicker mono"> 和 </p> 保持原样，明天你就会知道它们是什么。保存后：
git diff
git add index.html
git commit -m "首页小标题改为更新时间"
git push马上打开 Vercel 的项目页面，点 Deployments，能看到一条新部署，状态从 Building 变成 Ready，说明文字就是你的提交说明。
git push。收尾和预告
把网址记进 ~/code/learn/git-notes.md 的最后一行，然后在 learn 里提交并推送，顺便复习昨天的流程：
cd ~/code/learn
echo "旧官网已上线：https://dongge-site.vercel.app" >> git-notes.md
git add git-notes.md
git commit -m "记录旧官网的线上地址"
git push<p> 到底是什么。index.html。检查 GitHub 上文件是不是在最外层、文件名是不是全小写的 index.html；在项目的 Settings 里确认 Root Directory 是 ./、Framework Preset 是 Other、Output Directory 没有被改过。改完后在 Deployments 里对最新一次部署选择 Redeploy。git status 和 git log --oneline 检查。有新部署但页面没变，是浏览器缓存，电脑上按 Command + Shift + R 强制刷新。Street.JPG 和 street.jpg 是两个不同的文件，Mac 本地却不区分。照片文件名必须和 looks/README.txt 里写的完全一致，全小写。用自己的话讲一遍：在手机上打开官网网址，到页面出现，中间发生了什么？
一、手机拿到网址里的域名 dongge-site.vercel.app，先查缓存，没有就去问 DNS，得到 Vercel 服务器的 IP 地址。二、手机和这个 IP 的服务器建立连接，因为是 https，还要完成加密握手。三、浏览器发出 HTTP 请求 GET /，要首页。四、离我最近的 Vercel 节点找到我部署的 index.html，返回状态码 200、响应头和 HTML 内容。五、浏览器读 HTML，发现还需要字体、图片等，再分别发请求去要，有的返回 200，没放照片的返回 404。六、浏览器把 HTML、CSS 组合起来排版，运行 JavaScript，把页面画在屏幕上。
今天你亲眼见到了哪几个状态码？各自在什么情况下出现，分别是谁那边的问题？
200：正常打开首页，成功。308：用 http 打开时，Vercel 告诉浏览器“请改用 https 的地址”，属于重定向，不是错误。404：访问 /deploy.sh 或还没放进去的照片，服务器上没有这个文件，4 开头表示请求的东西有问题。还没见到的 500 表示服务器自己出错，等以后写后端时才会遇到。
为什么你只运行了 git push，网站就自动更新了？这中间 GitHub 和 Vercel 各做了什么？
导入仓库时，Vercel 和你的 GitHub 仓库建立了连接。你 push 到 main 分支后，GitHub 收到新提交，通知 Vercel“有新代码了”。Vercel 拉取最新代码，按项目设置处理（这个项目选了 Other，不需要构建，直接发布文件），生成一个新的部署，并把正式网址指向这次部署。你在 Deployments 列表里看到的每一行，就是一次 push 触发的一次部署。
~/code/learn/about.html“关于东哥”页面。昨天你在旧官网里改了一行 <p class="kicker mono">……</p>，只动了中间的文字。今天就来弄明白两边那些尖括号是什么。
想象你在搬家，每个箱子外面都贴一张标签：“衣服”“书”“易碎”。箱子里装的东西没变，但搬家师傅一看标签就知道怎么处理。HTML（HyperText Markup Language，超文本标记语言）做的就是这件事：给网页里的每一段内容贴上标签，告诉浏览器“这是大标题”“这是一段话”“这是一个链接”。浏览器根据标签决定怎么显示。
HTML 不是用来“计算”的编程语言，它是一种标记语言，只负责描述内容的结构。长什么样由 CSS 管（DAY 06 开始学），点了会怎样由 JavaScript 管（DAY 13 开始学）。今天只关心“有什么内容、内容之间是什么关系”。
HTML 文件就是一个普通的文本文件，扩展名是 .html。你可以用 VS Code 写，用浏览器打开。改完保存，浏览器刷新，就能看到变化。
为什么要认真选标签，而不是随便让字显示出来就行？因为读你 HTML 的不只是浏览器。至少还有三位“读者”：
所以写 HTML 时，先问自己“这段内容是什么”，而不是“我想让它长什么样”。
拿一行真实的代码来拆：
<a href="https://example.com/xiaohongshu">小红书</a><a> 是开始标签，</a> 是结束标签，多了一个斜杠。a 是 anchor（锚）的缩写，表示链接。href="https://example.com/xiaohongshu" 是属性，写在开始标签里，给元素补充信息。格式是 名字="值"，值用英文双引号包起来。href 告诉浏览器“点了去哪里”。有些元素没有内容，也就没有结束标签，叫空元素。比如图片：
<img src="images/dongge.jpg" alt="东哥的半身照" />图片的信息全在属性里，不需要中间的内容。末尾的 / 可写可不写，VS Code 里的 Prettier 保存时会自动加上，你看到它不用奇怪。
元素可以一层套一层，这叫嵌套，像俄罗斯套娃：
<p>在你面前<strong>三岁</strong>。</p>strong 在 p 里面，所以 strong 是 p 的子元素，p 是 strong 的父元素。嵌套的规则是：后打开的先关闭。下面这种交叉写法是错的：
<p>在你面前<strong>三岁。</p></strong>它就像先拉外套拉链、再扣里面衬衫的扣子，顺序反了。浏览器会尽力猜你的意思，但猜的结果常常不是你想要的。
还有一种特殊写法叫注释：<!-- 这里是注释 -->。注释里的内容浏览器不显示，用来给自己写备忘。
一个完整的 HTML 文件，外面总有一层固定的骨架：
learn/about.html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>关于东哥</title>
</head>
<body>
<h1>关于三岁的东哥</h1>
</body>
</html>逐行解释：
<!DOCTYPE html>：告诉浏览器“这是现代 HTML 文档”。固定写法，放在第一行。<html lang="zh-CN">：整个页面的根元素，其他所有元素都在它里面。lang="zh-CN" 说明页面主要语言是简体中文，读屏软件和搜索引擎会用到。<head>：页面的“档案信息”，这里的内容大多不直接显示在页面上。<meta charset="UTF-8" />：文字编码用 UTF-8。少了它，中文可能显示成乱码。<meta name="viewport" …/>：让手机按屏幕的真实宽度显示页面，而不是把电脑版缩小。DAY 11 会细讲，现在照写。<title>：浏览器标签页上显示的标题，也是分享链接和收藏时显示的名字。<body>：页面上真正显示的所有内容都写在这里。注意代码的缩进：head 和 body 比 html 往里缩了两格，meta 和 title 又比 head 往里缩了两格。缩进对浏览器没有影响，但它让人一眼看出谁装在谁里面。浏览器读完 HTML，会在内存里把所有元素排成一棵“树”：html 是树根，分出 head 和 body 两根树枝，每根树枝上再长出更小的枝叶。缩进就是这棵树画在纸上的样子。下午你会在开发者工具里亲眼看到这棵树，DAY 19 学 JavaScript 时，它有一个正式的名字叫 DOM。
.html 文件后，输入一个英文感叹号 ! 再按 Tab，会自动生成骨架。这个功能叫 Emmet。生成的 lang="en" 要手动改成 zh-CN。不过今天请先手敲一遍骨架，敲熟了再用快捷方式。HTML 有六级标题：h1 到 h6，数字越小级别越高。它们像一本书的目录：h1 是书名，h2 是章，h3 是节。
<h1>关于三岁的东哥</h1>
<h2>我的三个世界</h2>
<h2>在这些地方找到我</h2>h1，说明整页是关于什么的。h1 下面直接写 h4。段落用 <p>。在 HTML 里，你在代码中敲的回车和连续空格都会被合并成一个空格，所以换段要靠 <p>，不能靠回车。实在需要在段内换行（比如一首诗），用 <br />，但不要用它来拉开间距。
举个例子：你在代码里把“球房里安静的一小时，只有球声和呼吸。”拆成三行来写，中间还敲了好几个空格，浏览器照样把它显示成一行，只在拆开的地方留一个空格。这不是出错，而是 HTML 的规则：代码怎么排版是写给人看的，页面怎么排版由标签和 CSS 决定。
两个表示强调的标签：<strong> 表示“这很重要”，浏览器默认显示为粗体；<em> 表示“这里要加重语气”，默认显示为斜体。
<p>我是东哥。在外面是绅士、拳手、潮男，在你面前<strong>三岁</strong>。</p>内容是一条一条并列的，就用列表。HTML 有两种常用列表：
<ul>：无序列表（unordered list），每项前面是圆点，适合没有先后之分的内容，比如三个世界。<ol>：有序列表（ordered list），每项前面自动编号，适合有顺序的内容，比如每周节目单。不管哪种，每一项都用 <li>（list item）包起来，而且 li 必须直接放在 ul 或 ol 里面。
<ul>
<li><strong>绅士</strong>：斯诺克，马甲衬衫皮鞋。想给你的是<em>安全感</em>。</li>
<li><strong>街头</strong>：BMX 和滑板，Baggy 裤、Vans、Oversize。想给你的是<em>心动</em>。</li>
<li><strong>泰风</strong>：泰拳和泰国元素，泰拳短裤。想给你的是<em>被保护感</em>。</li>
</ul>每个 li 里又嵌套了 strong 和 em。列表还能套列表：在某个 li 里再放一个 ul，就是二级列表。
链接用 <a>，关键属性是 href：
<a href="https://example.com/tiktok" target="_blank" rel="noopener">TikTok</a>
<a href="index.html">回到首页</a>
<a href="mailto:hello@example.com">hello@example.com</a>https:// 开头，指向别的网站。target="_blank" 表示在新标签页打开，这样访客看完 TikTok 还能回到你的页面。rel="noopener" 是配套的安全设置，防止新页面反过来控制你的页面，用 _blank 时就一起写上。mailto: 开头，点击会打开邮件软件，收件人自动填好。课件里的平台链接都用 https://example.com/xiaohongshu 这类占位地址，等页面做好了，记得换成你自己的主页链接。
图片用 <img>，两个属性必写：
<img src="images/dongge.jpg" alt="东哥的半身照" width="320" />src（source）：图片地址。这里是相对路径，意思是“和 about.html 同级的 images 文件夹里的 dongge.jpg”。alt（alternative text）：图片的文字描述。图片加载失败时显示它；视障用户的读屏软件会把它念出来；搜索引擎也靠它理解图片。写清楚图里是什么，不要写“图片”两个字。width：显示宽度，单位是像素，可以不写。先用它防止大照片撑满屏幕，DAY 06 学了 CSS 以后改用 CSS 控制。相对路径是新手最容易出错的地方，画出文件夹结构就清楚了。今天的 learn 文件夹是这样的：
learn/
├── about.html
├── images/
│ └── dongge.jpg
└── drafts/
└── three-worlds.txt站在 about.html 的位置看：images/dongge.jpg 是“往下进 images 文件夹，拿 dongge.jpg”；如果 HTML 文件本身在更深一层的文件夹里，就要先写 ../ 回到上一层再往下走。规则和终端里的 cd 完全一样。路径里不要写 /Users/dong/… 这种只在你电脑上存在的地址，上传到网上就失效了。
这是今晚的验收题。打开任何一个网页，你会发现有的元素自己独占一行，有的元素和文字挤在同一行。
块级元素像书架上的一层隔板：不管里面东西多少，都占满整行宽度，前后自动换行，一个接一个从上往下排。常见的有 h1 到 h6、p、ul、ol、li、div。
行内元素像句子里的一个词：只占自己内容那么宽，和前后的文字排在同一行，放不下才折到下一行。常见的有 a、strong、em、span、code，还有 img（图片虽然有宽高，但默认也像一个字一样排在行内）。
看一个马上会遇到的例子。如果把四个平台链接直接写在一起：
<a href="https://example.com/xiaohongshu">小红书</a>
<a href="https://example.com/tiktok">TikTok</a>
<a href="https://example.com/facebook">Facebook</a>它们会挤在同一行，中间只隔一个空格，因为 a 是行内元素，代码里的换行被当成了空格。把每个链接放进 li，再放进 ul，就变成一行一个，因为 li 是块级元素。这就是为什么下午的平台链接要用列表来写。反过来，如果你发现某段文字莫名其妙地换了行，多半是它被包进了一个块级元素。
两个“万能容器”要认识一下：<div> 是没有任何含义的块级容器，<span> 是没有任何含义的行内容器。当你只是想把几样东西包在一起，方便以后加样式，又找不到更合适的标签时才用它们。明天会学到一批“有含义”的块级标签，大多数时候应该优先用它们。
一个经验：块级元素里可以放行内元素，比如 p 里放 a；反过来不行，不要在 a 或 span 里放 p、h2 这样的块级元素。
块级和行内只是浏览器的默认显示方式，以后学了 CSS 可以改。但今天先记住默认行为，因为你写的每一个标签都会从这里出发。
准备文件夹和一张照片
cd ~/code/learn
mkdir images
ls挑一张你自己的照片（最好是竖版半身照），用隔空投送或数据线传到 Mac，放进 ~/code/learn/images/，改名为 dongge.jpg。如果照片在“下载”文件夹里，可以用终端：
cp ~/Downloads/你的照片文件名.jpg images/dongge.jpg
ls imagesiPhone 的照片常常是 .HEIC 格式，部分浏览器不支持。可以用 Mac 自带的 sips 转成 JPG：
sips -s format jpeg ~/Downloads/IMG_1234.HEIC --out images/dongge.jpgls images 显示 dongge.jpg，文件名全小写。新建 about.html，手敲骨架
touch about.html
code .在 VS Code 里打开 about.html，照着上午第 3 节的骨架一个字一个字敲，不要复制。敲的时候心里念每一行的作用。保存后在终端运行：
open about.html写两段自我介绍
在 h1 下面加两个段落。第一段用 strong 强调“三岁”，第二段用你自己的话介绍你拍什么。记住“说事情不说情话”：写你做的事，不写甜言蜜语。
<p>我是东哥。在外面是绅士、拳手、潮男，在你面前<strong>三岁</strong>。</p>
<p>我拍短视频，记录三个世界里的日常：球房、滑板场、拳馆。</p>加上照片
在两段介绍下面加一张图片：
<img src="images/dongge.jpg" alt="东哥的半身照" width="320" />把 alt 改成对你这张照片的真实描述，比如“东哥穿着马甲衬衫站在球台旁”。
src 改成 images/dong.jpg 再刷新，照片消失，出现一个破图标和 alt 文字。看完改回来。三个世界的无序列表
加一个二级标题“我的三个世界”，下面用 ul 写三项，每项的世界名用 strong，给人的感受用 em。代码见上午第 5 节，同样手敲。
每周节目单的有序列表
<h2>每周节目单</h2>
<ol>
<li>周四：三岁时刻</li>
<li>周五：三岁换装</li>
<li>周日：今天带你去</li>
</ol>ol 的开始和结束标签都改成 ul，编号变成圆点。想想节目单为什么更适合用 ol，然后改回来。四个平台链接和合作邮箱
加一个二级标题“在这些地方找到我”，下面用 ul 放四个链接，每个都在新标签页打开。最后加一段合作邮箱。
<h2>在这些地方找到我</h2>
<ul>
<li><a href="https://example.com/xiaohongshu" target="_blank" rel="noopener">小红书</a></li>
<li><a href="https://example.com/tiktok" target="_blank" rel="noopener">TikTok</a></li>
<li><a href="https://example.com/facebook" target="_blank" rel="noopener">Facebook</a></li>
<li><a href="https://example.com/instagram" target="_blank" rel="noopener">Instagram</a></li>
</ul>
<p>合作请发邮件：<a href="mailto:hello@example.com">hello@example.com</a></p>对照完整代码检查
写完后，你的文件应该和下面差不多（文案可以是你自己的）。逐行对比，找出你漏掉或写错的地方。
learn/about.html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>关于东哥</title>
</head>
<body>
<h1>关于三岁的东哥</h1>
<p>我是东哥。在外面是绅士、拳手、潮男，在你面前<strong>三岁</strong>。</p>
<p>我拍短视频，记录三个世界里的日常：球房、滑板场、拳馆。</p>
<img src="images/dongge.jpg" alt="东哥的半身照" width="320" />
<h2>我的三个世界</h2>
<ul>
<li><strong>绅士</strong>：斯诺克，马甲衬衫皮鞋。想给你的是<em>安全感</em>。</li>
<li><strong>街头</strong>：BMX 和滑板，Baggy 裤、Vans、Oversize。想给你的是<em>心动</em>。</li>
<li><strong>泰风</strong>：泰拳和泰国元素，泰拳短裤。想给你的是<em>被保护感</em>。</li>
</ul>
<h2>每周节目单</h2>
<ol>
<li>周四：三岁时刻</li>
<li>周五：三岁换装</li>
<li>周日：今天带你去</li>
</ol>
<h2>在这些地方找到我</h2>
<ul>
<li><a href="https://example.com/xiaohongshu" target="_blank" rel="noopener">小红书</a></li>
<li><a href="https://example.com/tiktok" target="_blank" rel="noopener">TikTok</a></li>
<li><a href="https://example.com/facebook" target="_blank" rel="noopener">Facebook</a></li>
<li><a href="https://example.com/instagram" target="_blank" rel="noopener">Instagram</a></li>
</ul>
<p>合作请发邮件：<a href="mailto:hello@example.com">hello@example.com</a></p>
</body>
</html>在开发者工具里看块级和行内
在浏览器里对页面按 Command + Option + I，点 Elements（元素）标签。把鼠标移到左侧代码里的不同元素上，页面上对应的区域会被高亮。
<p> 上：高亮区域横跨整个页面宽度，哪怕文字只有半行。<strong>三岁</strong> 上：高亮只包住“三岁”两个字。h2、li、a、img。故意写错一次，看看会怎样
把第一段里 </strong> 删掉，保存刷新。你会发现“三岁”后面的内容都变粗了，因为浏览器以为强调一直没结束。看完按 Command + Z 撤销。
再试试用 Git 救回来：随便删掉几行，保存，然后：
git diff
git restore about.html注意：about.html 必须先提交过一次，git restore 才能救它。所以先做下一步的第一次提交，再回来做这个实验。
提交并推送到 GitHub
cd ~/code/learn
git status
git add about.html images/dongge.jpg
git commit -m "手写关于东哥页面：介绍、三个世界、节目单、平台链接"
git pushabout.html 和 images/dongge.jpg。明天你会新建 ~/code/links 项目，用更有含义的标签和一个留言表单，开始做真正要上线的链接主页。head 里少了 <meta charset="UTF-8" />，或者写错了位置。它要放在 head 的最前面。learn/images/ 里；文件名和 src 里的完全一致，包括大小写和扩展名（.jpg 和 .jpeg 是不同的）；格式不是 HEIC。Finder 默认会隐藏扩展名，用 ls images 看真实文件名最可靠。"。VS Code 里属性值正常会显示成统一的颜色，颜色突然不对就是信号。strong、em 或 a 没有写结束标签。从出问题的地方往上找最近的那个开始标签。块级元素和行内元素有什么区别？各举 3 个例子。
块级元素默认独占一行，宽度撑满父元素，前后自动换行，一个接一个从上往下排，例如 h1、p、ul（还有 li、div）。行内元素只占自己内容的宽度，和前后内容排在同一行，放不下才折行，例如 a、strong、em（还有 span、img、code）。块级元素里可以放行内元素，反过来不应该。这是浏览器的默认显示方式，以后可以用 CSS 改变。
指出下面这行代码里的开始标签、结束标签、属性名、属性值和内容，并说说 alt 为什么不能省。
<a href="https://example.com/instagram" target="_blank" rel="noopener">Instagram</a>
<img src="images/dongge.jpg" alt="东哥的半身照" />第一行：开始标签 <a …>，结束标签 </a>，属性名 href、target、rel，对应的值是网址、_blank、noopener，内容是“Instagram”。第二行是空元素，没有结束标签和内容，属性是 src 和 alt。alt 在图片加载失败时显示，读屏软件会念给视障用户听，搜索引擎也靠它理解图片，所以要写清楚图里是什么。
about.html 放在 ~/code/learn/，照片放在 ~/code/learn/images/dongge.jpg。如果把 about.html 挪进一个新文件夹 ~/code/learn/pages/，src 应该改成什么？为什么？
改成 ../images/dongge.jpg。相对路径从 HTML 文件所在的文件夹算起。挪到 pages/ 后，要先用 .. 回到上一层 learn/，再进入 images/。这和终端里 cd .. 是同一个规则。
src、alt、width 等属性href、target、rel 的写法header、nav、main、section、footer 各自用在哪，并在链接主页里正确使用它们。input、select、textarea、button 的表单，每个输入框都有配对的 label。button 而不是 div，为什么 input 要配 label，并能用键盘现场验证。~/code/links 项目，写出链接主页的完整骨架，提交到 Git 并推到 GitHub。昨天你认识了 div 和 span 这两个万能容器。理论上，整个页面都可以用 div 搭出来，加上 CSS 看起来也一模一样。那为什么还需要别的标签？
想象走进一家商场。如果每层楼都没有指示牌，你也能逛，只是要一家一家试。如果有“服务台”“餐饮区”“出口”的牌子，你一眼就知道往哪走。语义化标签就是网页里的指示牌：它们长得和 div 没区别（默认都是块级元素，没有特别的样式），但名字本身就说明了“这块区域是干什么的”。
语义化带来三个实际的好处：
index.html，看到 <footer> 就知道是页脚，看到一堆 <div> 只能一层层往里找。原则很简单：有合适的语义标签就用它，找不到才用 div。今天你要从零开始写的链接主页，就是练习这个原则的好机会。
一个典型网页可以分成几个区域，每个区域都有对应的标签：
| 标签 | 含义 | 在链接主页里放什么 |
|---|---|---|
header | 页面或某个区块的开头部分 | 头像、名字、一句话介绍 |
nav | 一组主要的导航链接 | 小红书、TikTok、Facebook、Instagram 四个按钮 |
main | 页面的主要内容 | 平台按钮和留言区 |
section | 一个有主题的内容区块，通常带标题 | “给东哥留言”这一块 |
footer | 页面或某个区块的结尾部分 | 版权信息 |
几条使用规则：
main 一个页面只能有一个，里面放“这个页面独有的主要内容”。每页都重复出现的东西（比如网站 Logo、页脚）放在 main 外面。section 里面通常要有一个标题（h2 或 h3）。如果你想不出这块内容该叫什么标题，说明它可能不是一个 section，用 div 更合适。nav 只用于重要的导航。对链接主页来说，那四个平台链接就是整页最重要的一组链接，放进 nav 很合理。页脚里零散的一两个链接则不需要。header 和 footer 不一定只在页面最上面和最下面，一个 section 也可以有自己的 header。今天先只用在整页上。新手常犯的错，是学了 section 以后看到什么都包一层 section。判断方法是问自己两个问题：这块内容能不能起一个像样的标题？把它单独拿出来，放进页面目录里，别人能不能看懂？两个都是“能”，就用 section；只是为了把几样东西包在一起方便排版，就用 div。比如“给东哥留言”能起标题，也能单独成立，是 section；而把输入框和它的 label 包在一起只是为了排版，用 div。
链接主页的结构画出来是这样：
body
├── header 头像、名字、一句话
├── main
│ ├── nav 四个平台按钮
│ └── section 给东哥留言（表单）
└── footer 版权信息今天的代码里会出现很多 class="..."，比如 <img class="avatar">、<a class="platform-btn">。class 是一个可以写在任何元素上的属性，作用是给元素起一个“分组名”。它本身不会改变任何显示效果，明天学 CSS 时，你会用这些名字告诉浏览器“所有叫 platform-btn 的元素都做成圆角按钮”。
起名习惯：用小写英文，多个单词之间用短横线连接，名字说明“它是什么”而不是“它长什么样”。叫 platform-btn 好，叫 black-box 不好，因为明天你可能把它改成白色。
还有一个相似的属性叫 id。区别是：class 可以很多元素共用一个；id 在整个页面里必须唯一，像身份证号。今天 id 只用在一个地方：让 label 找到它对应的输入框。
表单是网页收集访客信息的方式：登录框、搜索框、留言框都是表单。整个表单用 <form> 包起来，里面放各种输入控件。
links/index.html
<form class="message-form">
<label for="nickname">你的昵称</label>
<input type="text" id="nickname" name="nickname" placeholder="可以不填" />
</form>逐个解释：
<input> 是单行输入框，空元素，没有结束标签。type="text" 表示输入普通文字。type 还有很多种：email（邮箱，手机上会弹出带 @ 的键盘）、number（数字）、checkbox（勾选框）等，用对了类型，手机键盘会自动切换，访客输入更方便。id="nickname" 给这个输入框一个唯一的名字，给 label 用。name="nickname" 是提交表单时这项数据的“字段名”。服务器收到的数据长这样：nickname=小鹿。没有 name 的输入框，数据不会被提交。placeholder 是框里的浅灰色提示文字，访客一开始输入就消失。label 是输入框的说明文字。for="nickname" 和 input 的 id="nickname" 必须一模一样，两者才算配对。配对后有两个效果：点击文字“你的昵称”，光标会自动跳进输入框，手机上手指点不准时特别有用；读屏软件读到这个输入框时，会念出“你的昵称，文本输入框”，否则只会念“文本输入框”，用户不知道该填什么。
label 还有另一种写法：把 input 直接包在 label 里面，比如 <label>你的昵称 <input …/></label>，这样不写 for 和 id 也能配对。两种都对。本课程统一用 for 加 id 的写法，因为以后用 CSS 排版时，label 和 input 分开更灵活，DAY 21 用 JavaScript 读取输入值时也会用到这个 id。
placeholder 不能代替 label。访客一开始打字，提示就消失了，写到一半忘了这格填什么，只能全删掉重看。读屏软件对 placeholder 的支持也不稳定。留言表单还需要三种控件。
textarea：多行文字框，适合写一段话。它有结束标签，两个标签中间的内容是默认值，通常留空。rows="4" 表示默认显示 4 行高。
<label for="message">想对东哥说的话</label>
<textarea id="message" name="message" rows="4" placeholder="比如：想看你从零教滑板"></textarea>select：下拉选择框。每个选项是一个 option。value 是提交给服务器的值，标签中间的文字是访客看到的。这里我们让 value 用英文 slug（gentleman、street、thai），这正是后面数据库里 World 表用的值，从今天起就保持一致。
<label for="world">你更想看哪个世界</label>
<select id="world" name="world">
<option value="gentleman">绅士：斯诺克</option>
<option value="street">街头：BMX 和滑板</option>
<option value="thai">泰风：泰拳</option>
</select>下拉框默认选中第一个选项。如果想默认选中别的，比如街头，就在那个 option 上加一个 selected 属性。这种不需要值、写上就生效的属性叫布尔属性，后面的 disabled 也是。
button：按钮。它的 type 属性决定点了之后做什么：
type="submit"：提交表单。放在 form 里的按钮，不写 type 时默认就是 submit。type="button"：普通按钮，点了什么也不做，等 JavaScript 来给它安排任务。DAY 20 的风格切换按钮就会用它。<button type="submit">发送</button>表单现在还没有地方可以“寄”。点发送时，浏览器会用默认方式提交：把数据拼在网址后面，重新打开当前页面。你会在地址栏看到类似 index.html?nickname=小鹿&world=street&message=... 的内容，这就是 name=值 的样子，多项之间用 & 连接。今天先这样，DAY 21 用 JavaScript 接管提交，DAY 43 让留言真正存进数据库。
这是今晚的验收题。用 CSS 可以把一个 div 打扮得和按钮一模一样，为什么还要用 button？因为 button 天生带着一整套能力，div 一样都没有：
div 根本跳不到，只用键盘的人就永远点不了它。div 只会被念成一段普通文字。div 必须另写 JavaScript 才能做到。disabled），样式和行为会一起变。这类“让所有人都能用”的考虑，有一个专门的名字叫无障碍（Accessibility，常缩写成 a11y）。它不只关乎视障用户。你的观众里，有人在地铁上单手刷手机，有人把系统字号调得很大，有人手机屏幕碎了一角，有人外接键盘在电脑上看。选对标签、配好 label，就是让这些人都能顺利点进你的小红书、给你留下一句话。它几乎不增加工作量，只要从一开始养成习惯。
顺便分清 a 和 button：去一个地方用 a，做一件事用 button。四个平台按钮点了是跳转到小红书、TikTok 等网站，所以是 a，只是明天会用 CSS 把它们做成按钮的样子。“发送”是在当前页面做一件事，所以是 button。
从今天到 DAY 22，你会一直做同一个项目：链接主页，放在 ~/code/links。它就是你放进各平台简介里的那个网址，访客点进来能看到你是谁，一键跳到你的各个平台，还能给你留言。
项目会逐步长出这几个文件：
index.html：页面结构，今天写。avatar.jpg：头像，今天放进去。style.css：样式，DAY 06 开始写。script.js：交互，DAY 19 开始写。data.json：平台链接等数据，DAY 22 加入。DAY 12 你会把它部署到 Vercel。所以从第一天起就用 Git 管理，每完成一块就提交一次。
写 HTML 的顺序也有讲究：先搭结构，再写内容，最后才管样式。今天只关心“页面上有什么、它们是什么关系”，不管颜色、大小、位置。页面看起来又挤又丑完全没关系，那是明天 CSS 的工作。如果今天就想着“这里要居中”“那里要变大”，很容易为了样式去选错标签。一个检验方法：把 CSS 全部去掉，页面从上往下读，内容顺序依然通顺、合理，结构就是对的。
建项目文件夹，放好头像
mkdir -p ~/code/links
cd ~/code/links
git init
cp ~/code/learn/images/dongge.jpg avatar.jpg
touch index.html
ls头像先用昨天那张照片。如果你有一张更适合当头像的正方形照片，用它替换 avatar.jpg，文件名保持不变。
ls 显示 avatar.jpg 和 index.html；git init 输出了 Initialized empty Git repository。写骨架
code .在 index.html 里写好骨架，title 写“三岁的东哥 · 链接主页”。这次可以试试输入 ! 再按 Tab 生成，然后把 lang="en" 改成 lang="zh-CN"。
open index.html 后，浏览器标签页显示“三岁的东哥 · 链接主页”，页面是空白的。写 header：头像、名字、一句话
在 body 里写：
<header class="profile">
<img src="avatar.jpg" alt="东哥的头像" class="avatar" width="96" height="96" />
<h1>三岁的东哥</h1>
<p class="tagline">在外面是绅士、拳手、潮男，在你面前三岁。</p>
</header>写 main 和 nav：四个平台按钮
在 header 后面写：
<main>
<nav class="platforms">
<a class="platform-btn" href="https://example.com/xiaohongshu" target="_blank" rel="noopener">小红书</a>
<a class="platform-btn" href="https://example.com/tiktok" target="_blank" rel="noopener">TikTok</a>
<a class="platform-btn" href="https://example.com/facebook" target="_blank" rel="noopener">Facebook</a>
<a class="platform-btn" href="https://example.com/instagram" target="_blank" rel="noopener">Instagram</a>
</nav>
</main>四个链接先都用 example.com 占位，做完后换成你真实的主页地址。
a 是行内元素。明天和后天会把它们变成漂亮的按钮。写留言区 section 和表单
在 </nav> 后面、</main> 前面写：
<section class="message">
<h2>给东哥留言</h2>
<form class="message-form">
<label for="nickname">你的昵称</label>
<input type="text" id="nickname" name="nickname" placeholder="可以不填" />
<label for="world">你更想看哪个世界</label>
<select id="world" name="world">
<option value="gentleman">绅士：斯诺克</option>
<option value="street">街头：BMX 和滑板</option>
<option value="thai">泰风：泰拳</option>
</select>
<label for="message">想对东哥说的话</label>
<textarea id="message" name="message" rows="4" placeholder="比如：想看你从零教滑板"></textarea>
<button type="submit">发送</button>
</form>
</section>写 footer
在 </main> 后面、</body> 前面写：
<footer>
<p>© 2026 三岁的东哥</p>
</footer>测试 label 和键盘操作
Mac 上的 Safari 默认按 Tab 不会跳到链接，可以用 Chrome 测试，或在 Safari 设置的“高级”里打开“按下 Tab 键以高亮显示网页上的每个项目”。
点一次发送，看看数据去了哪里
填上昵称“小鹿”，世界选街头，留言写“想看滑板入门”，点发送。
?nickname=...&world=street&message=...，中文会显示成一串 %E5 这样的编码，这是网址里中文的正常写法。你能指出这里的 nickname、world、message 分别来自哪个元素的 name 属性。做个对比实验：把 button 换成 div
临时把发送按钮改成：
<div>发送</div>保存刷新，再用 Tab 走一遍，然后在留言框里按回车试试，再用鼠标点这个“发送”。
<button type="submit">发送</button>。对照完整代码
links/index.html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>三岁的东哥 · 链接主页</title>
</head>
<body>
<header class="profile">
<img src="avatar.jpg" alt="东哥的头像" class="avatar" width="96" height="96" />
<h1>三岁的东哥</h1>
<p class="tagline">在外面是绅士、拳手、潮男，在你面前三岁。</p>
</header>
<main>
<nav class="platforms">
<a class="platform-btn" href="https://example.com/xiaohongshu" target="_blank" rel="noopener">小红书</a>
<a class="platform-btn" href="https://example.com/tiktok" target="_blank" rel="noopener">TikTok</a>
<a class="platform-btn" href="https://example.com/facebook" target="_blank" rel="noopener">Facebook</a>
<a class="platform-btn" href="https://example.com/instagram" target="_blank" rel="noopener">Instagram</a>
</nav>
<section class="message">
<h2>给东哥留言</h2>
<form class="message-form">
<label for="nickname">你的昵称</label>
<input type="text" id="nickname" name="nickname" placeholder="可以不填" />
<label for="world">你更想看哪个世界</label>
<select id="world" name="world">
<option value="gentleman">绅士：斯诺克</option>
<option value="street">街头：BMX 和滑板</option>
<option value="thai">泰风：泰拳</option>
</select>
<label for="message">想对东哥说的话</label>
<textarea id="message" name="message" rows="4" placeholder="比如：想看你从零教滑板"></textarea>
<button type="submit">发送</button>
</form>
</section>
</main>
<footer>
<p>© 2026 三岁的东哥</p>
</footer>
</body>
</html>提交，并推到 GitHub
cd ~/code/links
echo ".DS_Store" > .gitignore
git add .
git commit -m "链接主页骨架：头像、介绍、四个平台链接、留言表单"
gh repo create links --private --source=. --remote=origin
git push -u origin maingh repo view --web 打开的 GitHub 页面上能看到 index.html、avatar.jpg、.gitignore。DAY 12 上线时会直接用这个仓库。明天开始给它穿上衣服：写第一个 style.css。label 的 for 和 input 的 id 不完全一样。常见错误是大小写不同、多了空格，或者把 for 写成了 name 的值而 id 写的是别的。两边复制同一个词最保险。name 属性。id 是给 label 和以后的 CSS、JavaScript 用的，name 才是提交数据用的，两个都要写。<textarea> 和 </textarea> 之间的所有内容都会成为默认值，包括空格和换行。两个标签要紧挨着写。avatar.jpg 没有复制到 ~/code/links/ 里，或者文件名不对。在 links 文件夹里运行 ls 确认。git remote add origin 加上仓库地址，再 git push -u origin main。为什么按钮要用 button 而不是 div？为什么 input 要配 label？
button 天生能被 Tab 键选中、能用回车或空格触发，读屏软件会念出“按钮”，放在表单里还能直接提交表单，也能设为禁用；div 只是一个没有含义的盒子，这些能力一样都没有，只用键盘或读屏软件的人就用不了它。
input 配上 label（for 等于 id）后，点击文字就能聚焦输入框，扩大了可点区域，手机上尤其好用；读屏软件读到输入框时会念出 label 的文字，用户知道该填什么。placeholder 一打字就消失，不能代替 label。
下面这段结构有两处不合适，找出来并说明理由。
<main>
<div class="platforms">……四个平台链接……</div>
<section>
<p>© 2026 三岁的东哥</p>
</section>
</main>第一，四个平台链接是整页最重要的一组导航链接，用 nav 比 div 更准确。第二，版权信息属于页脚，应该放在 main 外面的 footer 里；而且这个 section 没有标题，也说明它不适合做 section。
小红书按钮用的是 a，发送按钮用的是 button。它们都“长得像按钮”，为什么标签不一样？
判断标准是“去一个地方”还是“做一件事”。点小红书按钮是跳转到另一个网址，属于导航，用 a，它有 href，可以在新标签页打开、可以复制链接。点发送是在当前页面提交表单，属于操作，用 button。外观可以用 CSS 做成一样，但标签要按用途选。
style.css 接到 index.html 上，读懂“选择器、属性、值”组成的一条 CSS 规则。box-sizing: border-box 解决了什么问题。style.css 里哪一行造成的。昨天的链接主页结构完整，但看起来又挤又素：四个链接挤在一行，表单控件贴在一起。今天给它穿上衣服。
如果说 HTML 是房子的结构（哪里是客厅、哪里是卧室），CSS（Cascading Style Sheets，层叠样式表）就是装修：墙刷什么颜色、地板铺多宽、家具之间留多大距离。同一套结构，换一份 CSS，可以从北欧风变成工业风。DAY 09 你会亲手体验这一点：同一个页面，切换成绅士、街头、泰风三种风格。
CSS 有三种写法，但我们只用一种：单独写一个 .css 文件，在 HTML 的 head 里用 link 引入。
links/index.html
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>三岁的东哥 · 链接主页</title>
<link rel="stylesheet" href="style.css" />
</head>rel="stylesheet" 说明引入的是样式表，href 是文件路径，和图片的相对路径规则一样。另外两种写法是把 CSS 写在 HTML 里的 <style> 标签中，或直接写在元素的 style 属性上。它们会让结构和样式混在一起，页面一多就难以维护，所以不用。
一条 CSS 规则长这样：
links/style.css
.platform-btn {
background-color: #2f4f4f;
color: #ffffff;
}.platform-btn 是选择器：选中哪些元素。这里是所有 class 为 platform-btn 的元素，也就是四个平台链接。属性: 值;。background-color 是属性（背景色），#2f4f4f 是值（一种深绿灰）。CSS 的注释写法是 /* 注释内容 */，用来给代码分段，写上“这一段管头部”“这一段管按钮”，以后找起来快。
你可能注意到，昨天没写任何 CSS，页面也不是完全没有样式：h1 又大又粗，链接是蓝色带下划线，页面四周有一圈白边。这是因为每个浏览器都自带一份默认样式表。我们写的 CSS 会覆盖它。今天好几条规则，比如 body { margin: 0; }、text-decoration: none，就是在去掉浏览器的默认样式，换成我们自己的。在开发者工具里，这些默认样式会标着“user agent stylesheet”。
今天用到五种选择器：
| 写法 | 叫法 | 选中谁 |
|---|---|---|
body | 元素选择器 | 所有 body 元素 |
.avatar | class 选择器 | 所有 class 里有 avatar 的元素，前面加一个点 |
header, main, footer | 组合（分组） | 三者都选中，共用同一组声明，用逗号隔开 |
.message h2 | 后代选择器 | class 为 message 的元素里面的 h2，用空格隔开 |
* | 通配选择器 | 页面上所有元素 |
还有 id 选择器，写法是 #nickname。它的“权重”很高，会压过 class 选择器，用多了以后很难覆盖，所以写样式时优先用 class。
如果两条规则给同一个元素设置了同一个属性，谁说了算？记住两条就够用：
h2 { color: black; } 和 .message h2 { color: green; }，留言区里的 h2 是绿色，因为后者更具体。另一个重要概念是继承：有些属性设在父元素上，子元素会自动跟着用，比如 color、font-family、line-height。所以字体和文字颜色只要设在 body 上，整页都生效。而 margin、padding、border、背景色这类“盒子”属性不会继承。
CSS 里写颜色有几种方式：
white、black、tomato。好记，但选择有限，适合临时试验。#2f4f4f。井号后面六位，每两位一组，分别是红、绿、蓝的强度，从 00（没有）到 ff（最强）。#ffffff 是白，#000000 是黑。设计软件和配色网站给的颜色大多是这种写法，最常用。rgb(47 79 79)，直接写红绿蓝三个 0 到 255 的数字，和上面的 #2f4f4f 是同一个颜色。想要半透明，加一个斜杠和透明度：rgb(0 0 0 / 50%) 是半透明的黑。常用的颜色属性有三个：color（文字颜色）、background-color（背景色）、border 里的颜色（边框色）。
今天先用一套偏“绅士”的配色：米白背景 #f4f1ea，深色文字 #1f2a2e，灰色辅助文字 #5b6770，按钮用深绿灰 #2f4f4f。这几个颜色 DAY 09 会变成“变量”，并给街头和泰风各做一套。
字体用 font-family 设置，值是一串用逗号隔开的字体名：
body {
font-family: -apple-system, "PingFang SC", "Helvetica Neue", Arial, sans-serif;
}为什么写一串？因为访客的设备上不一定有你想要的字体。浏览器从左往右找，第一个找到的就用。-apple-system 是苹果设备的系统字体，"PingFang SC" 是苹果的中文字体苹方，名字里有空格的要加引号；Arial 是几乎所有电脑都有的英文字体；最后的 sans-serif 是兜底，意思是“随便给我一个无衬线字体”。这一串叫字体栈。DAY 09 你会学到用 Google Fonts 引入网上的字体，就不用依赖访客的电脑了。
其他常用的文字属性：
font-size：字号，比如 16px、2rem。font-weight：粗细，400 是正常，600 是半粗，700 是粗体。line-height：行高。写成不带单位的 1.6，意思是字号的 1.6 倍。中文段落行高 1.6 到 1.8 读起来比较舒服。text-align：水平对齐，center 是居中。text-decoration：文字装饰，none 可以去掉链接默认的下划线。写大小和距离时要带单位。今天用三种：
12px 在哪都是 12px。适合边框粗细、小间距这类“不需要跟着变”的地方。1rem 等于 16px，2rem 等于 32px。好处是：如果访客在手机设置里把默认字号调大，用 rem 写的字号会跟着一起变大，页面对视力不好的人更友好。所以字号优先用 rem。width: 100% 是“和父元素一样宽”。适合让元素撑满容器，比如输入框。border-radius: 50% 则是一个特例：把正方形的四个角圆到一半，就成了圆形，头像就是这样做成圆的。还有一个常见的 em，它相对于当前元素自己的字号，嵌套多了容易算乱，暂时不用。
一个简单的选择口诀：字号用 rem，宽度用 %，边框和小间距用 px。今天的代码基本照这个来。等你写多了，会慢慢形成自己的判断，不必死守。
这是 CSS 最核心的概念，也是今晚的验收题。在浏览器眼里，页面上每个元素都是一个矩形盒子，这个盒子由里到外有四层：
用快递箱打比方：content 是箱子里的衣服，padding 是衣服周围塞的泡沫，border 是纸箱本身，margin 是这个箱子和旁边箱子之间留的空隙。
.platform-btn {
display: block;
margin-bottom: 12px;
padding: 14px 20px;
border-radius: 12px;
}padding: 14px 20px; 两个值时，第一个是上下，第二个是左右。按钮文字上下各留 14px、左右各留 20px，按钮就变得“好点”。margin-bottom: 12px; 只设下外边距，让按钮之间隔开 12px。margin 和 padding 都可以分别设置 -top、-right、-bottom、-left。margin: 上 右 下 左;。border-radius 是圆角半径，不属于四层之一，但常和盒子一起用。display: block; 为什么需要？因为 a 是行内元素，行内元素设置的上下 margin 不起作用，也不会独占一行。改成 block 后，它就像一个块级盒子，占满整行、四层都能设置。这就是 DAY 04 说的“块级和行内是默认行为，CSS 可以改”。还有一个新手必踩的坑：默认情况下，width 只算 content 的宽度。你给输入框写 width: 100%，再加上左右 padding 和 border，它的实际宽度就会超过 100%，从卡片右边戳出去。解决办法是在 CSS 最前面加上：
* {
box-sizing: border-box;
}意思是让所有元素的 width 包含 padding 和 border。写 100% 就是真的 100%。几乎所有网站都会加这一条，你以后每个项目也都加上。
margin 还有一个特别的脾气，叫外边距合并：两个上下相邻的块级元素，上面那个的 margin-bottom 是 20px，下面那个的 margin-top 是 30px，它们之间的距离不是 50px，而是取较大的 30px。就像两个人都说“离我一米远”，他们之间只需要隔一米，而不是两米。遇到“间距怎么比我算的小”时，先想想是不是合并了。左右方向的 margin 不会合并。
最后一个常用技巧：块级元素设置了 max-width（最大宽度）以后，再写 margin: 0 auto;，上下外边距是 0，左右外边距由浏览器自动平分，它就在页面里水平居中了。电脑屏幕很宽时，内容不会被拉得太长，读起来更舒服。
写 CSS 时最有用的工具就在浏览器里。在 Chrome 里右键页面上任意元素，选“检查”（或按 Command + Option + I），打开 Elements 面板：
style.css:52。被覆盖掉的声明会被划一道横线。你还可以直接在 Styles 里改数值、勾掉某条声明，页面会立刻变化，适合试验“改成多少合适”。但这些改动刷新就没了，试好了要回 style.css 里真正写下来。
找“某处间距是谁造成的”的方法：选中间距两边的元素之一，看 Computed 里 margin 或 padding 哪个有数值，再到 Styles 里找到写这个值的那条规则，右上角的文件名和行号就是答案。
新建 style.css 并接到页面上
cd ~/code/links
touch style.css
code .在 index.html 的 head 里、title 下面加一行：
<link rel="stylesheet" href="style.css" />在 style.css 里先写一条测试规则：
body {
background-color: tomato;
}全局设置：盒模型、字体、颜色
links/style.css
/* ===== 全局 ===== */
* {
box-sizing: border-box;
}
body {
margin: 0;
font-family: -apple-system, "PingFang SC", "Helvetica Neue", Arial, sans-serif;
font-size: 16px;
line-height: 1.6;
color: #1f2a2e;
background-color: #f4f1ea;
}body 默认有 8px 的外边距，margin: 0 把它去掉，页面边缘就由我们自己控制。
三大区域限宽并居中
/* ===== 三大区域：限制宽度并居中 ===== */
header,
main,
footer {
max-width: 960px;
margin: 0 auto;
padding: 24px 16px;
}头部：圆形头像、标题、介绍
/* ===== 头部 ===== */
.profile {
text-align: center;
}
.avatar {
border-radius: 50%;
border: 3px solid #ffffff;
object-fit: cover;
}
.profile h1 {
margin: 8px 0 4px;
font-size: 2rem;
line-height: 1.2;
}
.tagline {
margin: 0;
color: #5b6770;
}object-fit: cover 让照片按比例裁切，填满 96×96 的方框而不被压扁。text-align: center 设在 header 上，里面的文字和图片（图片默认是行内元素，也会跟着居中）都居中了。
平台按钮
/* ===== 平台按钮 ===== */
.platform-btn {
display: block;
margin-bottom: 12px;
padding: 14px 20px;
border-radius: 12px;
background-color: #2f4f4f;
color: #ffffff;
font-weight: 600;
text-align: center;
text-decoration: none;
}留言区做成一张白色卡片
/* ===== 留言区 ===== */
.message {
margin-top: 32px;
padding: 24px;
border-radius: 16px;
background-color: #ffffff;
}
.message h2 {
margin: 0 0 8px;
font-size: 1.25rem;
}表单控件和发送按钮
label {
display: block;
margin: 16px 0 6px;
font-weight: 600;
}
input,
select,
textarea {
width: 100%;
padding: 10px 12px;
border: 1px solid #c9c2b4;
border-radius: 8px;
font: inherit;
}
.message-form button {
margin-top: 20px;
padding: 12px 28px;
border: none;
border-radius: 999px;
background-color: #1f2a2e;
color: #ffffff;
font: inherit;
font-weight: 600;
cursor: pointer;
}label 改成 block，每个说明文字独占一行，在输入框正上方。font: inherit：浏览器默认给表单控件用另一套较小的字体，这一句让它们继承页面的字体。font 是一个“简写属性”，会把粗细也一起重置，所以 button 里 font-weight 要写在它后面。.message-form button 是后代选择器，只选中留言表单里的按钮。以后页面上还会有别的按钮（比如 DAY 20 的风格切换按钮），这样写不会误伤它们。border-radius: 999px：圆角大到超过按钮高度的一半，两端就变成半圆，是做“胶囊按钮”的常用写法。cursor: pointer：鼠标移上去变成小手，提示可以点。页脚
/* ===== 页脚 ===== */
footer {
text-align: center;
font-size: 0.875rem;
color: #5b6770;
}footer 在第 3 步的分组里已经出现过，这里再写一次也没问题：两条规则会合并，属性不冲突就都生效。
用开发者工具查看盒模型
在“小红书”按钮上右键，选“检查”。
.platform-btn 规则，右上角写着 style.css 和行号。padding 的值，改成 24px 20px，看按钮立刻变高。再点声明前面的勾选框把它勾掉，看按钮变扁。刷新页面，一切恢复。style.css 第几行的 margin-bottom: 12px。做个实验：去掉 box-sizing
在 style.css 最前面的 box-sizing: border-box; 前加上注释符号，变成 /* box-sizing: border-box; */，保存刷新。
对照完整代码
你的 style.css 现在应该包含上面第 2 到第 8 步的全部内容，顺序是：全局、三大区域、头部、平台按钮、留言区（含 label、输入控件、button）、页脚。逐段对照，特别检查每条声明结尾的分号和每个大括号是否成对。
提交并推送
git add index.html style.css
git commit -m "链接主页加上基础样式：配色、字体、按钮、留言卡片"
git pushstyle.css。现在四个按钮是竖着排的，明天用 Flexbox 让它们在手机上竖排、在电脑上横排。link 的 href 是否正好是 style.css，文件是不是和 index.html 在同一个文件夹；style.css 保存了没有；浏览器刷新了没有。开发者工具的 Network 面板里，如果 style.css 是 404，就是路径错了。platform-btn { }；或者 HTML 和 CSS 里的名字拼得不一样，比如 platform-btn 和 platfrom-btn。a 是行内元素，上下外边距不起作用。先加 display: block;（明天学了 Flexbox 还有别的办法）。style.css 并保存。margin 和 padding 有什么区别？用开发者工具找出页面上任意一处间距是哪行 CSS 造成的。
padding 是内边距，在边框里面，是内容和边框之间的空间，元素的背景色会铺满它，点击 padding 区域也算点到了这个元素；margin 是外边距，在边框外面，是这个盒子和其他盒子之间的距离，永远透明，不属于元素的可点区域。比如按钮要“好点”，加大的是 padding；按钮之间要隔开，用的是 margin。
演示方法：右键“小红书”按钮选“检查”，在 Computed 的盒模型图里看到下方 margin 是 12；切到 Styles，找到写着 margin-bottom: 12px 的 .platform-btn 规则，右上角显示 style.css 和行号，这就是两个按钮之间间距的来源。
下面两条规则都作用在留言区的标题上，标题最终是什么颜色？为什么？
.message h2 {
color: #2f4f4f;
}
h2 {
color: tomato;
}深绿灰 #2f4f4f。虽然 h2 写在后面，但 .message h2 包含一个 class，比只有元素名的 h2 更具体，更具体的规则优先。只有两条规则一样具体时，才是写在后面的胜出。在开发者工具的 Styles 里能看到 tomato 那一条被划了横线。
为什么字号推荐用 rem 而不是 px？为什么输入框宽度用 100% 而不是 343px？
rem 相对于根元素字号，访客在手机或浏览器设置里调大默认字号时，用 rem 写的文字会跟着变大，对视力不好的人更友好；px 是固定的，不会跟着变。输入框用 100% 是让它始终和父元素一样宽，不同手机屏幕宽度不同，写死 343px 在宽屏上会显得短，在窄屏上会溢出；配合 box-sizing: border-box，100% 就正好包含 padding 和 border。
flex-direction 改变的是什么。justify-content、align-items、gap、flex-wrap 排列一组元素，通关 Flexbox Froggy 全部 24 关。flex: 1 1 200px 三个数字的意思，并用它让平台按钮在手机上竖排、在电脑上横排。昨天你用 display: block 把平台链接变成了四个竖排的按钮。可如果想让它们横着排成一行，或者让头像、名字、介绍整齐地居中对齐，只靠 margin 和 padding 就很别扭。在 Flexbox 出现之前，前端开发者要用各种“偏方”来做横排和居中，“垂直居中”甚至是一个流传多年的笑话。
Flexbox（弹性盒子布局）就是专门解决“把一组元素沿一个方向排好”的工具。想象一根晾衣绳：衣服（子元素）挂在绳子（容器）上，你可以决定衣服从左边挂起还是挤在中间、彼此隔多远、绳子挂满了要不要再拉一根。Flexbox 让你用几个属性就说清这些事。
用法的第一步，永远是在父元素上写 display: flex：
links/style.css
.platforms {
display: flex;
}写了这一行，.platforms（也就是那个 nav）就成了 flex 容器，它的直接子元素（四个 a）就成了 flex 子项。注意是“直接子元素”，孙子辈的元素不受影响。子项会立刻从上下排列变成左右排成一行。
Flexbox 擅长的是一维排列：一行，或者一列。一排按钮、一个竖着的头部、一条导航栏，都是一维的。如果要同时控制行和列，比如“三张卡片排成网格，手机一列、电脑三列”，那是二维布局，明天学的 Grid 更合适。今天先把一维练熟，因为页面上大多数小排版都是一维的。
还有一个变化：子项原来是块级还是行内都不重要了。四个 a 原本是行内元素，成为 flex 子项后，它们都能正常设置宽高、padding 和 margin，所以昨天为按钮写的 display: block 可以去掉了。
Flexbox 里有两个方向，一定要分清：
主轴的方向由容器上的 flex-direction 决定：
row（默认）：主轴水平，子项从左到右排成一行。column：主轴竖直，子项从上到下排成一列。row-reverse 和 column-reverse，顺序反过来，用得少。关键在于：改了 flex-direction，两根轴会一起转。设成 column 以后，主轴变成上下，交叉轴变成左右。下面学的 justify-content 永远管主轴，align-items 永远管交叉轴。所以同一句 align-items: center，在 row 里是“上下居中”，在 column 里就变成了“左右居中”。这一点通关 Froggy 时你会反复体会。
遇到任何 Flexbox 问题，先按这个顺序问自己三个问题：谁是容器？flex-direction 是什么，所以主轴朝哪？我要调的是主轴方向还是交叉轴方向？三个问题答完，该用哪个属性基本就清楚了。把这个习惯带进下午的练习里，比背下所有属性名更有用。
justify-content 写在容器上，决定子项在主轴上怎么摆，以及多余的空间怎么分。以三个世界的标签横排为例：
| 取值 | 效果 |
|---|---|
flex-start（默认） | 全部挤在主轴起点，也就是左边 |
center | 全部挤在中间 |
flex-end | 全部挤在终点，也就是右边 |
space-between | 第一个贴左边，最后一个贴右边，中间平均分开 |
space-around | 每个子项两侧留同样的空，所以两端的空是中间的一半 |
space-evenly | 所有空隙完全相等，包括两端 |
最常用的是 center 和 space-between。比如网站顶部的导航条，左边放名字、右边放菜单，就是 space-between。
要理解 justify-content，关键是“多余的空间”这几个字。它分配的是子项排完之后剩下的空间。如果子项已经把一整行占满了（比如下面会讲的 flex-grow 让按钮自动撑满），就没有剩余空间可分，justify-content 写什么都看不出区别。所以当你发现“改了 justify-content 没反应”时，先看看这一行还有没有空地。
align-items 也写在容器上，决定子项在交叉轴上怎么对齐：
stretch（默认）：子项在交叉轴方向拉伸，填满容器。所以横排时，几个按钮会自动一样高，哪怕其中一个文字多了一行。flex-start：贴着交叉轴起点。center：交叉轴居中。flex-end：贴着交叉轴终点。baseline：让各子项的文字底线对齐，字号不同的文字排在一行时用。链接主页的头部就要用到它。头像、名字、一句话要从上到下排列并且水平居中，写法是：
.profile {
display: flex;
flex-direction: column;
align-items: center;
gap: 8px;
}逐行看：变成 flex 容器；主轴改成竖直方向，三样东西从上到下排；此时交叉轴是水平方向，align-items: center 就是水平居中；gap 让它们之间各隔 8px。
text-align: center 也让头部居中了，为什么还要换？text-align 只管“行内内容”在一行里的位置，对有固定宽度的块级元素无效；Flexbox 管的是“盒子”本身的位置，不管里面是什么都能居中，控制也更精确。多行的介绍文字仍然需要 text-align: center 让每一行居中，所以两者会一起保留。gap 设置子项之间的间距。昨天你给每个按钮加了 margin-bottom: 12px，最后一个按钮下面也多出了 12px。gap: 12px 只在子项之间留空，两端不留，更干净。以后排一组元素，优先用 gap 而不是给每个子项加 margin。
flex-wrap 决定放不下时怎么办。默认是 nowrap：子项宁可被压扁也要挤在一行。改成 wrap：一行放不下，就换到下一行接着排，像写字写到行尾自动换行。
.platforms {
display: flex;
flex-wrap: wrap;
gap: 12px;
}在手机这样的窄屏上，四个按钮不可能舒服地挤在一行，所以要允许换行。换行以后，gap 同时管左右和上下的间距。
换行还有一个容易忽略的特点：每一行是各算各的。第一行放了三个按钮，这三个按钮只分第一行的空间；被挤到第二行的按钮，独自分第二行的空间。所以如果第二行只剩一个按钮，它会占满整行，比上面的按钮宽得多。下面第 6 节算平板宽度时，你会看到这个现象。
前面的属性都写在容器上。还有一个重要属性写在子项上：flex。它是三个属性的简写：
.platform-btn {
flex: 1 1 200px;
}1 是 flex-grow（放大比例）：一行里有多余的空间时，子项按这个比例分掉。都是 1，就平均分。写 0 则不放大。1 是 flex-shrink（缩小比例）：空间不够时，子项按这个比例缩小。200px 是 flex-basis（基础尺寸）：子项在分配空间之前的“理想宽度”。配合容器上的 flex-wrap: wrap，这一行就实现了“手机竖排、电脑横排”。算一下你就明白：
flex 还有几种常见的简写，读别人的代码时会遇到：flex: 1 表示“放大比例 1，可以缩小，基础尺寸 0”，几个子项都写 flex: 1 就会完全平分一行，不管内容多少；flex: none 表示“既不放大也不缩小，就按自己的大小”，适合头像这种不能变形的东西。
这就是 Flexbox 的“弹性”：你不告诉它屏幕多宽，它自己算。唯一的不完美在平板宽度：内容区约 736px 时，一行放得下 3 个，第 4 个被挤到第二行并独自撑满整行。明天学了媒体查询，你可以精确地说“屏幕多宽时怎么排”，把这个问题修掉。
把一个方块放到页面正中间，是今晚的验收题，也是 Flexbox 最经典的用法：
learn/center.css
body {
margin: 0;
min-height: 100vh;
display: flex;
justify-content: center;
align-items: center;
}display: flex：让 body 成为容器，方块成为子项。justify-content: center：主轴（水平）居中。align-items: center：交叉轴（竖直）居中。min-height: 100vh：这一行最容易被忘记。body 默认只有内容那么高，方块多高它就多高，在它里面“竖直居中”等于没动。vh 是视口高度的单位，100vh 就是整个浏览器窗口的高度。body 至少和窗口一样高，竖直居中才看得出效果。margin: 0：去掉 body 默认的 8px 外边距，否则页面会多出一点滚动条。三行核心代码，记成一句话：父元素 flex，主轴居中，交叉轴居中，父元素要够高。
上午读完这些以后，打开 Flexbox Froggy（flexboxfroggy.com），右上角可以切换成简体中文。它是一个小游戏：每一关你要写几行 CSS，把小青蛙送到同色的荷叶上。24 关覆盖了今天所有的属性，还会顺带教你三个新属性：
order：写在子项上，改变它在队伍里的顺序，数字小的排前面。HTML 里的顺序不变，只是显示顺序变了。align-self：写在子项上，让这一个子项在交叉轴上“特立独行”，不听容器的 align-items。align-content：写在容器上，只在换行后有多行时才起作用，决定这几行整体在交叉轴上怎么分布。它和 align-items 很容易混：align-items 管“每一行里的子项怎么对齐”，align-content 管“这几行之间怎么摆”。卡住时回来看第 2 节：先想清楚主轴是哪个方向，再决定用 justify 还是 align。每关写对后不要急着点下一关，先用一句话说出你用的属性管的是哪根轴，这比通关本身更重要。最后几关会把多个属性组合起来，正好复习整个上午的内容。
通关 Flexbox Froggy
如果上午还没通关，先打开 https://flexboxfroggy.com/ ，右上角语言选简体中文，完成全部 24 关。每关写完，停下来用一句话说出你用的属性管的是哪根轴。
头部改用 Flexbox 竖排居中
打开 ~/code/links/style.css，把 .profile 和 .profile h1 两条规则改成：
links/style.css
.profile {
display: flex;
flex-direction: column;
align-items: center;
gap: 8px;
text-align: center;
}
.profile h1 {
margin: 0;
font-size: 2rem;
line-height: 1.2;
}h1 的上下外边距改成 0，间距统一交给 gap 管理。.tagline 本来就是 margin: 0，不用改。
flex 小标签。平台按钮：容器
在“平台按钮”那一段的最前面，新加一条规则：
.platforms {
display: flex;
flex-wrap: wrap;
gap: 12px;
}display: block 和 margin-bottom，下一步处理。平台按钮：子项
把 .platform-btn 改成下面这样：删掉 display: block; 和 margin-bottom: 12px;，在最前面加上 flex: 1 1 200px;。
.platform-btn {
flex: 1 1 200px;
padding: 14px 20px;
border-radius: 12px;
background-color: #2f4f4f;
color: #ffffff;
font-weight: 600;
text-align: center;
text-decoration: none;
}用手机模拟模式检查
打开开发者工具，按 Command + Shift + M（或点左上角的手机平板图标）打开设备模拟工具栏。在顶部的设备下拉框里选一款 iPhone，再选 iPad，最后关掉模拟回到电脑宽度。DAY 11 会细讲这个工具。
用开发者工具的 Flexbox 编辑器试验
在 Elements 里选中 nav class="platforms"，在 Styles 的 .platforms 规则里，display: flex 旁边有一个小图标，点开是 Flexbox 编辑器。依次点不同的 justify-content 和 align-items 按钮，看按钮怎么移动。再临时把 flex-wrap 改成 nowrap，把窗口拉窄，看按钮被压扁。
验收练习：新建居中练习页
cd ~/code/learn
touch center.html center.css
code center.html center.csslearn/center.html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>居中练习</title>
<link rel="stylesheet" href="center.css" />
</head>
<body>
<div class="box">三岁</div>
</body>
</html>learn/center.css
body {
margin: 0;
min-height: 100vh;
display: flex;
justify-content: center;
align-items: center;
background-color: #f4f1ea;
}
.box {
width: 120px;
height: 120px;
display: flex;
justify-content: center;
align-items: center;
border-radius: 16px;
background-color: #2f4f4f;
color: #ffffff;
font-size: 1.5rem;
}这里用了两次居中：body 让方块在页面中间，.box 自己也是 flex 容器，让“三岁”两个字在方块中间。
open center.html 后，深色方块在窗口正中间，“三岁”在方块正中间。随意拉伸窗口，方块始终居中。拆掉一行看看
依次把 center.css 里 body 的这几行注释掉，每次只注释一行，保存刷新，观察变化，再恢复：min-height: 100vh、align-items: center、justify-content: center。
闭卷再写一遍
关掉课件，把 center.css 里 body 的规则全删掉，凭记忆重写，直到方块回到正中间。
两个仓库分别提交
cd ~/code/links
git add style.css
git commit -m "用 Flexbox 排版头部和平台按钮：手机竖排，电脑横排"
git push
cd ~/code/learn
git add center.html center.css
git commit -m "Flexbox 居中练习"
git pushdisplay: flex 写在了子项上，而不是父元素上。justify-content、align-items、gap、flex-wrap 都写在容器上；只有 flex 写在子项上。min-height: 100vh。flex-basis 是沿主轴方向的尺寸，主轴竖直时，200px 就成了高度。明天改成媒体查询写法时，要一起去掉这个 200px。margin-bottom: 12px 没删，和 gap 叠加了。用开发者工具的 Computed 查一下 margin。不看资料，把一个方块放到页面正中间（水平垂直都居中）。
body {
margin: 0;
min-height: 100vh;
display: flex;
justify-content: center;
align-items: center;
}
.box {
width: 120px;
height: 120px;
background-color: #2f4f4f;
}父元素（body）设为 flex 容器，justify-content: center 让方块在主轴（水平）居中，align-items: center 让方块在交叉轴（竖直）居中，min-height: 100vh 让 body 至少和窗口一样高，竖直居中才有空间。
头部用的是 flex-direction: column 加 align-items: center。为什么这里的 align-items 管的是左右，而不是上下？
align-items 永远管交叉轴。flex-direction 设成 column 后，主轴变成从上到下，交叉轴就变成左右方向，所以 align-items: center 是水平居中。如果是默认的 row，同一句就变成竖直居中。
平台按钮写的是 flex: 1 1 200px，容器写了 flex-wrap: wrap。如果把 200px 改成 100px，在 375px 宽的手机上会变成什么样？为什么？
内容区宽 343px。三个按钮需要 3 × 100 + 2 × 12 = 324px，放得下，第四个需要 436px，放不下。所以第一行排 3 个，平分这一行；第四个换到第二行，并用 flex-grow 撑满整行。这说明 flex-basis 决定了“什么时候开始换行”。
display: grid、grid-template-columns、fr、gap 排出一个多列网格，并说清 fr 是怎么分空间的。@media (min-width: 768px) 这样的媒体查询，解释“手机优先”是什么意思、为什么这样写。昨天的 Flexbox 擅长把一组东西沿一个方向排好。今天要做的“三个世界”卡片区，需求是：手机上一列，平板上两列，电脑上三列。这是在同时安排“行”和“列”，属于二维布局。
想象停车场地上画的格子线：先画好几列几行，车停进去自动对齐。Grid（网格布局）就是先在容器上“画线”，再让子元素一格一格填进去。和 Flexbox 一样，第一步是在父元素上声明：
links/style.css
.world-grid {
display: grid;
grid-template-columns: 1fr 1fr 1fr;
gap: 16px;
}display: grid：让 .world-grid 成为网格容器，它的直接子元素成为网格项。grid-template-columns：画列。这里写了三个值，就是三列，每个值是一列的宽度。gap: 16px：格子之间的间距，行和列都是 16px。和 Flexbox 的 gap 是同一个属性。你只画了列，没有画行。三张卡片会自动从左到右填满第一行；如果有第四张，会自动开一个新行放进去。行高默认由内容决定，最高的那张卡片多高，这一行就多高，同一行的卡片自动一样高。这种“自动排”让 Grid 特别适合卡片列表：数据多几条少几条，布局都不会乱。
你可能会想到 HTML 里的表格 table，它也有行和列。两者用途完全不同：table 是给数据用的，比如一张价目表、一份训练记录，行和列本身有含义；Grid 是给布局用的，只负责把东西摆整齐，HTML 里依然是一张张独立的卡片。早年网页曾用表格来排版，结果代码又长又难改，手机上也没法重新排列，这种做法已经被淘汰了。
fr 是 Grid 专用的单位，是 fraction（份）的缩写。它的意思是“把剩余空间分成几份，我占几份”。
1fr 1fr 1fr：三列各占一份，也就是平分成三等份。2fr 1fr：两列，第一列占两份，第二列占一份，左边是右边的两倍宽。200px 1fr：第一列固定 200px，第二列拿走所有剩下的空间。适合“左边固定宽度的侧栏，右边正文”这种布局。为什么不直接写 33.33%？因为百分比不会自动扣掉 gap。三列各 33.33% 再加上两个 16px 的间距，总宽度就超过 100%，会溢出。fr 分的是“扣掉 gap 和固定宽度之后剩下的空间”，永远刚好。
列数多了，重复写 1fr 很啰嗦，可以用 repeat() 函数：repeat(3, 1fr) 就等于 1fr 1fr 1fr，第一个参数是重复几次，第二个是每次写什么。
网格项还可以跨越多个格子。比如在网格项上写 grid-column: span 2，它就会横跨两列。下午有一个选做步骤会用到它。Grid Garden 里还会教你用 grid-column-start、grid-column-end 这些属性，按“第几条线”来精确摆放，我们的页面暂时用不到那么精细的控制，但通关时会练到。
你的观众大多用手机刷小红书和 TikTok，点进链接主页时屏幕只有三百多像素宽。合作方可能在电脑上打开，屏幕有一千多像素宽。同一份 HTML，要在两种屏幕上都好看好用。
一种办法是做两个网站，一个手机版一个电脑版。维护两份代码太累，改一处要改两遍。现在的通用做法是响应式设计：只有一个页面，CSS 根据屏幕宽度自动调整布局。手机上卡片一列竖排，电脑上三张并排，内容完全一样，只是排法不同。
响应式不只是改列数。随着屏幕变化，可能要调整的还有：字号（大标题在手机上要小一些）、间距（手机上留白少一点）、图片大小、按钮的排列方向。今天先做最核心的布局变化，字号和图片的适配留到 DAY 10 和 DAY 11。而“在真正的手机上打开检查”这一步，模拟器替代不了，DAY 11 会专门做。
实现响应式的核心工具，是媒体查询（media query）。
媒体查询是一种“有条件的 CSS”：只有条件成立时，里面的规则才生效。
@media (min-width: 768px) {
.world-grid {
grid-template-columns: repeat(2, 1fr);
}
}@media 开头，表示这是一个媒体查询。(min-width: 768px) 是条件：浏览器窗口的宽度至少是 768px，也就是 768px 或更宽时成立。媒体查询本身不提高优先级。它里面的 .world-grid 和外面的 .world-grid 一样具体，按“一样具体时写在后面的胜出”的规则，媒体查询要写在普通规则后面才能覆盖它。所以习惯上把所有媒体查询放在 CSS 文件的最后。
这些宽度的分界点叫断点（breakpoint）。本课程统一用两个断点：
| 屏幕宽度 | 大致设备 | 三个世界 | 平台按钮 |
|---|---|---|---|
| 小于 768px | 手机 | 一列 | 竖排 |
| 768px 到 1023px | 平板 | 两列 | 横排一行 |
| 1024px 及以上 | 电脑 | 三列 | 横排一行 |
断点不必和某款设备精确对应，原则是“内容在哪里开始显得别扭，就在哪里加断点”。768 和 1024 是常见的起点，够我们用了。
head 里那行 <meta name="viewport" content="width=device-width, initial-scale=1.0" />。少了它，手机浏览器会假装自己有 980px 宽，你写的手机样式就不会被用上。DAY 04 起每个页面都写了它，不要删。写响应式 CSS 有两种顺序：
min-width 的媒体查询，为更宽的屏幕逐步“加东西”。max-width 的媒体查询，为更窄的屏幕“打补丁”。本课程用手机优先，理由有三：你的观众主要在手机上；手机布局通常最简单（一列从上往下排），作为基础最干净；从简单往复杂加，比从复杂往简单删更不容易出错。以手机为起点，第一眼看到页面的大多数人得到的就是最用心的版本。
今天“三个世界”的完整写法就是这个思路：
.world-grid {
display: grid;
grid-template-columns: 1fr;
gap: 16px;
}
@media (min-width: 768px) {
.world-grid {
grid-template-columns: repeat(2, 1fr);
}
}
@media (min-width: 1024px) {
.world-grid {
grid-template-columns: repeat(3, 1fr);
}
}逐段看：不在任何媒体查询里的第一段，所有屏幕都会用，它定下了一列；窗口达到 768px，第二段也生效，把列数覆盖成两列；达到 1024px，第三段也生效，因为写在最后，它覆盖前两段，变成三列。窗口从窄拉到宽，列数就从 1 变 2 再变 3。
对比一下电脑优先会怎样：先写三列，再用 max-width: 1023px 改成两列，再用 max-width: 767px 改成一列。手机上要先加载三列的规则，再被两次覆盖才得到最终结果，改样式时也要记住“这条在哪个宽度下被谁覆盖了”。手机优先则是每一步只做加法，读代码时从上往下，就是屏幕从小到大的顺序，更容易理清。
DAY 10 你会读到官网的 CSS 用的是 max-width，也就是电脑优先。两种写法都对，读别人代码时先看清是哪一种。
这是今晚的验收题。简单的判断方法：
换一种说法：Flexbox 是“从内容出发”，先有东西，再看怎么排；Grid 是“从布局出发”，先画格子，再往里放东西。
拿你页面上的需求对照一下：
| 需求 | 用什么 | 理由 |
|---|---|---|
| 头像、名字、一句话竖着排并居中 | Flexbox | 只有一列，一维 |
| 四个平台按钮排成一行，平分宽度 | Flexbox | 只有一行，一维 |
| 方块放在页面正中间 | Flexbox | 一个子项，两个方向居中，三行代码最简单 |
| 三个世界卡片随屏幕变成一列、两列、三列 | Grid | 要同时管行和列，卡片要对齐成网格 |
| 以后的穿搭卡片墙，数量不固定 | Grid | 自动开新行，每行对齐 |
两者不是二选一，经常一起用。整个卡片区用 Grid 排成网格，每张卡片内部如果要让标题和标签左右分开，再用 Flexbox。现代 CSS 布局基本就是这两样工具的组合。
今天还会用到一个新标签 article：表示一块独立、完整的内容，拿出来单独看也说得通，比如一张卡片、一篇文章、一条评论。每张世界卡片就是一个 article。DAY 19 用 JavaScript 生成穿搭卡片时也会用它。
上午的最后一项是通关 Grid Garden（cssgridgarden.com），和 Flexbox Froggy 是同一个作者。右上角可以选简体中文。每一关你要写 CSS 给胡萝卜地浇水、给杂草喷药，共 28 关。
它的前半部分主要练 grid-column-start、grid-column-end、grid-row 这些“按线定位”的属性。网格线是从 1 开始编号的：三列的网格有 4 条竖线，第一列在第 1 条线和第 2 条线之间。理解了“线”的概念，前半部分就很顺。后半部分会练到 grid-template-columns、fr 和 repeat()，正是今天下午要用的内容。
卡关时，先在纸上画出网格和线的编号，再写代码。
通关 Grid Garden
如果上午没做完，先打开 https://cssgridgarden.com/ ，语言选简体中文，完成 28 关。
在 index.html 里加“三个世界”区块
打开 ~/code/links/index.html，在 </nav> 后面、留言区 <section class="message"> 前面加入：
links/index.html
<section class="worlds">
<h2>三个世界</h2>
<div class="world-grid">
<article class="world-card world-gentleman">
<h3>绅士</h3>
<p class="world-en">Gentleman</p>
<p>斯诺克，马甲衬衫皮鞋。安静地打完一局球。</p>
<p class="world-feeling">给你的感觉：安全感</p>
</article>
<article class="world-card world-street">
<h3>街头</h3>
<p class="world-en">Street</p>
<p>BMX 和滑板，Baggy 裤、Vans、Oversize。摔了就再来一次。</p>
<p class="world-feeling">给你的感觉：心动</p>
</article>
<article class="world-card world-thai">
<h3>泰风</h3>
<p class="world-en">Thai</p>
<p>泰拳和泰国元素，泰拳短裤。每天的训练从缠手带开始。</p>
<p class="world-feeling">给你的感觉：被保护感</p>
</article>
</div>
</section>为什么网格要单独包一层 div class="world-grid"，而不是直接让 section 当网格？因为 section 里还有标题 h2，如果 section 是网格容器，h2 也会变成一个格子，占掉第一格。每张卡片的第二个 class（world-gentleman 等）用来给它单独配颜色。卡片里的描述可以换成你自己的话，记得说事情，不说情话。
写卡片的基础样式（手机版）
在 style.css 里“平台按钮”那一段后面，加上“三个世界”这一段：
links/style.css
/* ===== 三个世界 ===== */
.worlds {
margin-top: 32px;
}
.worlds h2 {
margin: 0 0 16px;
font-size: 1.25rem;
}
.world-grid {
display: grid;
grid-template-columns: 1fr;
gap: 16px;
}
.world-card {
padding: 20px;
border-radius: 16px;
border-top: 6px solid #2f4f4f;
background-color: #ffffff;
}
.world-card h3 {
margin: 0;
font-size: 1.25rem;
}
.world-card p {
margin: 8px 0 0;
}
.world-en {
font-size: 0.75rem;
letter-spacing: 0.1em;
text-transform: uppercase;
color: #5b6770;
}
.world-feeling {
font-weight: 600;
}
.world-gentleman {
border-top-color: #2f4f4f;
}
.world-street {
border-top-color: #ff5a1f;
}
.world-thai {
border-top-color: #b5171f;
}border-top: 6px solid #2f4f4f 是简写，一次写好顶部边框的粗细、样式（实线）和颜色。letter-spacing 拉开字母间距，text-transform: uppercase 把英文全部显示成大写，HTML 里写的还是 Gentleman。.world-card 一样具体，写在后面，所以能覆盖。加平板断点：两列
在 style.css 的最后加上：
/* ===== 响应式：平板（768px 及以上） ===== */
@media (min-width: 768px) {
.world-grid {
grid-template-columns: repeat(2, 1fr);
}
}加电脑断点：三列
继续在最后加上：
/* ===== 响应式：电脑（1024px 及以上） ===== */
@media (min-width: 1024px) {
.world-grid {
grid-template-columns: repeat(3, 1fr);
}
}用响应式模式拖动宽度
打开开发者工具，按 Command + Shift + M 打开设备模拟工具栏，设备下拉框选 Responsive（自适应）。拖动页面右侧的把手改变宽度，同时看顶部显示的像素数。
用媒体查询修好平台按钮
昨天的写法在平板上是 3 加 1。现在改成“手机竖排，平板以上横排一行”。先把平台按钮那段里的 .platforms 改成竖排，并从 .platform-btn 里删掉 flex: 1 1 200px; 这一行：
.platforms {
display: flex;
flex-direction: column;
gap: 12px;
}
.platform-btn {
padding: 14px 20px;
border-radius: 12px;
background-color: #2f4f4f;
color: #ffffff;
font-weight: 600;
text-align: center;
text-decoration: none;
}然后在第 4 步的平板媒体查询里，.world-grid 规则的后面，加上两条规则。整个平板媒体查询变成：
/* ===== 响应式：平板（768px 及以上） ===== */
@media (min-width: 768px) {
.world-grid {
grid-template-columns: repeat(2, 1fr);
}
.platforms {
flex-direction: row;
}
.platform-btn {
flex: 1;
}
}竖排时，按钮靠 align-items 的默认值 stretch 自动撑满宽度；横排时，flex: 1 让四个按钮平分一行。去掉 flex-wrap 和 200px，是因为竖排时 flex-basis 会变成高度，昨天的常见坑里提到过。
选做：平板上让第三张卡片横跨两列
平板两列时，泰风卡片单独在第二行左边，右边空了一块。可以让它在平板宽度下横跨两列。在平板媒体查询里加：
.world-thai {
grid-column: span 2;
}在电脑媒体查询里加上恢复的规则，否则三列时它也会跨两列：
.world-thai {
grid-column: auto;
}用开发者工具查看网格线
在 Elements 面板里，div class="world-grid" 旁边有一个 grid 小标签，点一下，页面上会叠加显示网格线和线的编号。在不同宽度下分别打开看看。
提交并推送
cd ~/code/links
git add index.html style.css
git commit -m "加入三个世界区块：Grid 手机一列、平板两列、电脑三列；平台按钮改用媒体查询"
git push@media 和括号之间有空格、括号里是 min-width: 768px 而不是 min-width = 768px。head 里的 viewport 那一行还在不在。display: grid 写在了包含 h2 的 section 上。网格容器应该是只包着卡片的那个 div.world-grid。fr；长网址的问题 DAY 11 会处理。什么时候用 Flexbox，什么时候用 Grid？各举一个你页面上的例子。
Flexbox 适合一维排列：一行或一列，元素大小主要由内容决定，思路是“先有内容再排”。例子：链接主页的头部，头像、名字、介绍用 flex-direction: column 竖排居中；平台按钮在平板以上用 flex 横排并平分一行。
Grid 适合二维布局：同时控制行和列，容器先规划好格子，思路是“先画格子再放内容”。例子：“三个世界”卡片区，用 grid-template-columns 在手机、平板、电脑上分别排成一列、两列、三列，同一行的卡片自动一样高。两者可以嵌套使用。
下面这段 CSS，在 900px 宽的窗口里，.world-grid 是几列？在 1200px 宽的窗口里呢？如果把两个媒体查询的顺序对调，结果会变吗？
.world-grid { grid-template-columns: 1fr; }
@media (min-width: 768px) { .world-grid { grid-template-columns: repeat(2, 1fr); } }
@media (min-width: 1024px) { .world-grid { grid-template-columns: repeat(3, 1fr); } }900px 时，第一个媒体查询成立，第二个不成立，是两列。1200px 时，两个媒体查询都成立，它们一样具体，写在后面的 1024 那条胜出，是三列。如果对调顺序，1200px 时两条都成立，写在后面的变成了 768 那条，结果变成两列，三列永远不会出现。这就是手机优先要按宽度从小到大写媒体查询的原因。
grid-template-columns: 1fr 1fr 1fr 和 33.33% 33.33% 33.33%，在有 gap: 16px 的情况下有什么区别？
fr 分的是扣掉 gap 之后剩下的空间，三列加两个间距刚好等于容器宽度。百分比是按容器总宽度算的，三个 33.33% 已经约等于 100%，再加上两个 16px 的间距就超出容器，会溢出或出现横向滚动条。所以网格列宽优先用 fr。
:root 和定义在 body.theme-street 上有什么不同。:hover 和 :focus-visible 状态，用 transition 让变化平滑。这一周你的链接主页已经有了结构、样式和响应式布局。今天做一件很有“东哥味”的事：让同一个页面能切换成绅士、街头、泰风三种风格。
先看看现在的 style.css。深绿灰 #2f4f4f 出现在平台按钮、卡片色条等好几个地方，灰色 #5b6770 出现在介绍、页脚、英文标签里。如果要把整页换成街头风，你得找出每一处颜色，一个个改掉。漏掉一处，页面就会出现一块“不合群”的颜色。三套风格就是三倍的工作量。
做视频时你大概也有类似的经验：给一个系列定好“主色、辅色、字体”，每条视频都照着用，整个账号看起来才统一。想换风格时，改的是这份设定，而不是一条条视频重新调色。CSS 变量就是网页里的这份设定：把颜色、字体这些值起个名字，集中写在一个地方，其他地方都通过名字来用。改设定，所有用到它的地方一起变。
定义和使用变量的写法：
links/style.css
:root {
--accent: #2f4f4f;
}
.platform-btn {
background-color: var(--accent);
}--accent: #2f4f4f; 定义一个变量。变量名必须以两个短横线 -- 开头，后面起一个说明用途的名字。accent 的意思是“强调色”，也就是主色。:root 是一个特殊的选择器，指整个页面最外层的元素，也就是 <html>。变量定义在这里，全页都能用。var(--accent) 取出变量的值。写在任何需要颜色的地方都行。var(--accent, #2f4f4f)，意思是“如果没有定义 --accent，就用逗号后面的值”。变量名起得好很重要。叫 --green 不好，因为街头风的主色是橙色，到时候“green 等于橙色”会让人糊涂。按用途起名：--bg（背景）、--text（文字）、--accent（主色），换成什么颜色，名字都不会错。
CSS 变量和 color 一样会继承：定义在某个元素上，它自己和它里面的所有后代都能用。定义在 :root（html）上，全页都能用，因为所有元素都在 html 里面。
关键的一点：如果在更里面的元素上重新定义同一个变量，这个元素和它的后代就会用新值，外面的不受影响。
:root {
--accent: #2f4f4f;
}
body.theme-street {
--accent: #ff5a1f;
}body.theme-street 的意思是“class 里有 theme-street 的 body 元素”，元素名和 class 名紧挨着写，中间没有空格。当 body 上挂着 theme-street 这个 class 时，body 重新定义了 --accent，页面上所有用 var(--accent) 的地方，也就是 body 里的所有元素，都会拿到橙色。把 class 去掉，body 不再重新定义，大家又从 :root 继承到深绿灰。
这就是做主题切换的全部原理：
var()，不写具体的颜色值。body.theme-xxx 里。今天你手动改 class 来切换。DAY 20 学了 JavaScript，会做成点一下按钮就切换，还能记住访客的选择。到时候 JavaScript 只需要做一件事：换掉 body 上的 class。今天把地基打好，DAY 20 就很轻松。
theme-gentleman、theme-street、theme-thai 这三个 class 名，变量名统一用 --bg、--text、--accent 等。DAY 10 和 DAY 20 的课件都会用到这些名字，请照着写，不要自己改名。每套主题需要回答同样几个问题：背景什么色？文字什么色？次要文字什么色？主色是什么？卡片什么色？线条什么色？标题用什么字体？我们把这些都定成变量：
| 变量 | 用途 | 绅士 | 街头 | 泰风 |
|---|---|---|---|---|
--bg | 页面背景 | 米白 #f4f1ea | 近黑 #121212 | 暖米 #fff7ec |
--text | 正文文字 | 墨色 #1f2a2e | 近白 #f5f5f5 | 深棕 #2b1a12 |
--muted | 次要文字 | 灰 #5b6770 | 浅灰 #a3a3a3 | 棕灰 #7a5c4a |
--accent | 主色 | 墨绿 #2f4f4f | 亮橙 #ff5a1f | 泰拳红 #b5171f |
--card | 卡片背景 | 白 | 深灰 #1e1e1e | 白 |
--line | 输入框边线 | #c9c2b4 | #3a3a3a | #e8cfa9 |
--font-heading | 标题字体 | Playfair Display + 思源宋体 | Bebas Neue + 站酷庆科黄油体 | Kanit + 思源黑体 |
配色背后的想法，对应三个世界想给观众的感受：
这些颜色你完全可以换成自己喜欢的。只要守住一条：文字和背景要有足够的对比度，尤其是街头的深色主题，次要文字不能灰到看不清。
还有一些值不随主题变化，比如圆角大小、正文字体、三个世界各自的代表色（卡片顶部的色条）。它们单独放在一个 :root 里。把圆角也写成变量 --radius，整页的圆角就能保持一致，想整体调圆一点，改一处就行。“质感”很大程度上来自这种一致。
DAY 06 的字体栈只能用访客电脑上已经装了的字体。想用更有个性的字体，就要让浏览器从网上下载，这叫网络字体。Google Fonts（fonts.google.com）提供上千款免费、可商用的网络字体，其中也有中文字体。
使用步骤：在网站上搜索字体，进入字体页面点 Get font，选好要的字重，再点 Get embed code，它会给你一段 <link> 代码，复制到 HTML 的 head 里，放在你自己的 style.css 前面。今天需要的六款字体，合在一起是这样：
links/index.html
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Kanit:wght@400;700&family=Noto+Sans+SC:wght@400;700&family=Noto+Serif+SC:wght@700&family=Playfair+Display:wght@400;700&family=ZCOOL+QingKe+HuangYou&display=swap"
/>preconnect 让浏览器提前和 Google 的字体服务器建立连接，字体下载得更快。还记得 DAY 03 的“建立连接”那一步吗？这是在提前做它。family= 是一款字体，名字里的空格写成 +，wght@400;700 表示要常规和粗体两种字重，多款字体之间用 & 连接。display=swap：字体还没下载完时，先用备用字体把文字显示出来，下载好了再换上。这样网速慢时访客也不会对着空白等待。引入之后，在 font-family 里写字体的名字就能用。要注意两点：
"Playfair Display", "Noto Serif SC", serif：英文用 Playfair，中文用思源宋体（Noto Serif SC），都没有就用系统衬线字体。serif 或 sans-serif 兜底。好的按钮会“回应”你：鼠标移上去，它会有一点变化，告诉你“我可以点”。这些不同的时刻叫元素的状态，CSS 用伪类来选中它们，写法是在选择器后面加冒号：
.platform-btn:hover {
transform: translateY(-2px);
background-color: var(--text);
}
.platform-btn:focus-visible {
outline: 3px solid var(--text);
outline-offset: 3px;
}:hover：鼠标悬停在元素上时。这里让按钮往上浮起 2px，背景换成文字色。transform: translateY(-2px) 是“沿竖直方向移动 -2px”，负数是往上。它只是视觉上的移动，不会挤动周围的元素。:focus-visible：用键盘 Tab 选中元素时。还记得 DAY 05 用 Tab 键走过整个页面吗？只用键盘的人，全靠这一圈轮廓知道自己停在哪。outline 是画在边框外面的轮廓线，outline-offset 让它离按钮远一点，更醒目。两条原则：第一，手机没有“悬停”，手指一碰就是点击，所以重要的信息不能只藏在 hover 效果里。第二，不要给不能点的东西加 hover 效果，比如三个世界的卡片现在不能点，鼠标移上去也不应该浮起来，否则访客会以为能点，点了又没反应。
只写 :hover，按钮会“啪”地一下瞬间变色、瞬间跳起，显得生硬。transition（过渡）让属性值在一段时间里慢慢变过去：
.platform-btn {
transition: transform 0.2s ease, background-color 0.2s ease;
}属性名 时长 速度曲线。这里写了两组，用逗号隔开：transform 和 background-color 都用 0.2 秒过渡。0.2s 是 0.2 秒。按钮这类小交互一般在 0.15 到 0.3 秒之间，太慢会让人觉得卡。ease 是速度曲线：开始快、结束慢，最接近真实物体的运动。transition 写在元素本身的规则上，而不是写在 :hover 里。这样鼠标移上去和移开时，两个方向都有过渡。
也可以写 transition: all 0.2s 让所有属性都过渡，省事但不推荐：以后你改了别的属性，也会莫名其妙地跟着动起来。明确写出要过渡的属性，更可控。
今天还会给 body 加一条背景色和文字色的过渡。你在开发者工具里切换 body 的 class 时，整页颜色会用 0.3 秒平滑地变过去，DAY 20 点按钮切换风格时也会有这个效果。
今天的 style.css 会有一次比较大的整理，结构变成：
:root, body.theme-gentleman 是默认的绅士主题；body.theme-street、body.theme-thai 分别覆盖成街头和泰风。var()，标题统一用 var(--font-heading)。第 2 部分里的 :root, body.theme-gentleman 用了逗号，意思是两个选择器共用这组变量：body 上没有挂任何主题 class 时，从 :root 拿到绅士的值；挂了 theme-gentleman 时，也是绅士的值。这样即使忘了写 class，页面也不会因为变量不存在而变得一片空白。
还有一个小技巧：街头主题的标题字体（Bebas Neue、黄油体）只有一种字重，如果按默认的粗体显示，浏览器会“假装加粗”，笔画变糊。所以把标题字重也做成变量 --heading-weight，街头主题设为 400。变量不只能存颜色，任何值都可以。
引入 Google Fonts
打开 ~/code/links/index.html，在 head 里、<link rel="stylesheet" href="style.css" /> 这一行的上面，加入上午第 4 节的三个 link。
css2?family=... 的请求，状态 200。页面外观暂时还没变，因为还没在 CSS 里使用这些字体。给 body 挂上主题 class
把 <body> 改成：
<body class="theme-gentleman">在 style.css 最上面写好所有变量
打开 style.css，在最前面（* { box-sizing } 的上面）加入：
links/style.css
/* ===== 变量：不随主题变化 ===== */
:root {
--radius: 12px;
--radius-lg: 16px;
--font-body: "Noto Sans SC", -apple-system, "PingFang SC", sans-serif;
--world-gentleman: #2f4f4f;
--world-street: #ff5a1f;
--world-thai: #b5171f;
}
/* ===== 主题：绅士（默认） ===== */
:root,
body.theme-gentleman {
--bg: #f4f1ea;
--text: #1f2a2e;
--muted: #5b6770;
--accent: #2f4f4f;
--card: #ffffff;
--line: #c9c2b4;
--font-heading: "Playfair Display", "Noto Serif SC", serif;
--heading-weight: 700;
}
/* ===== 主题：街头 ===== */
body.theme-street {
--bg: #121212;
--text: #f5f5f5;
--muted: #a3a3a3;
--accent: #ff5a1f;
--card: #1e1e1e;
--line: #3a3a3a;
--font-heading: "Bebas Neue", "ZCOOL QingKe HuangYou", sans-serif;
--heading-weight: 400;
}
/* ===== 主题：泰风 ===== */
body.theme-thai {
--bg: #fff7ec;
--text: #2b1a12;
--muted: #7a5c4a;
--accent: #b5171f;
--card: #ffffff;
--line: #e8cfa9;
--font-heading: "Kanit", "Noto Sans SC", sans-serif;
--heading-weight: 700;
}:root, body.theme-gentleman 这条规则和它的 8 个变量。把全局和标题换成变量
把 body 规则改成下面这样，并在它后面新增标题字体的规则：
body {
margin: 0;
font-family: var(--font-body);
font-size: 16px;
line-height: 1.6;
color: var(--text);
background-color: var(--bg);
transition: background-color 0.3s ease, color 0.3s ease;
}
h1,
h2,
h3,
.world-en {
font-family: var(--font-heading);
}
h1,
h2,
h3 {
font-weight: var(--heading-weight);
}把其余颜色全部换成变量，加上状态和过渡
从 header, main, footer 那一段开始，一直到文件末尾，替换成下面的完整代码。它和你现有的代码结构完全一样，只是把颜色和圆角换成了 var()，并加上了 hover、focus 和 transition。如果你做了 DAY 08 的选做（泰风卡片跨两列），把那两条规则保留在对应的媒体查询里。
links/style.css
/* ===== 三大区域：限制宽度并居中 ===== */
header,
main,
footer {
max-width: 960px;
margin: 0 auto;
padding: 24px 16px;
}
/* ===== 头部 ===== */
.profile {
display: flex;
flex-direction: column;
align-items: center;
gap: 8px;
text-align: center;
}
.avatar {
border-radius: 50%;
border: 3px solid var(--card);
object-fit: cover;
}
.profile h1 {
margin: 0;
font-size: 2rem;
line-height: 1.2;
}
.tagline {
margin: 0;
color: var(--muted);
}
/* ===== 平台按钮 ===== */
.platforms {
display: flex;
flex-direction: column;
gap: 12px;
}
.platform-btn {
padding: 14px 20px;
border-radius: var(--radius);
background-color: var(--accent);
color: var(--bg);
font-weight: 600;
text-align: center;
text-decoration: none;
transition: transform 0.2s ease, background-color 0.2s ease;
}
.platform-btn:hover {
transform: translateY(-2px);
background-color: var(--text);
}
.platform-btn:focus-visible {
outline: 3px solid var(--text);
outline-offset: 3px;
}
/* ===== 三个世界 ===== */
.worlds {
margin-top: 32px;
}
.worlds h2 {
margin: 0 0 16px;
font-size: 1.25rem;
}
.world-grid {
display: grid;
grid-template-columns: 1fr;
gap: 16px;
}
.world-card {
padding: 20px;
border-radius: var(--radius-lg);
border-top: 6px solid var(--world-gentleman);
background-color: var(--card);
}
.world-card h3 {
margin: 0;
font-size: 1.25rem;
}
.world-card p {
margin: 8px 0 0;
}
.world-en {
font-size: 0.75rem;
letter-spacing: 0.1em;
text-transform: uppercase;
color: var(--muted);
}
.world-feeling {
font-weight: 600;
}
.world-gentleman {
border-top-color: var(--world-gentleman);
}
.world-street {
border-top-color: var(--world-street);
}
.world-thai {
border-top-color: var(--world-thai);
}
/* ===== 留言区 ===== */
.message {
margin-top: 32px;
padding: 24px;
border-radius: var(--radius-lg);
background-color: var(--card);
}
.message h2 {
margin: 0 0 8px;
font-size: 1.25rem;
}
label {
display: block;
margin: 16px 0 6px;
font-weight: 600;
}
input,
select,
textarea {
width: 100%;
padding: 10px 12px;
border: 1px solid var(--line);
border-radius: 8px;
background-color: var(--bg);
color: var(--text);
font: inherit;
transition: border-color 0.2s ease;
}
input:focus,
select:focus,
textarea:focus {
border-color: var(--accent);
outline: 2px solid var(--accent);
}
.message-form button {
margin-top: 20px;
padding: 12px 28px;
border: none;
border-radius: 999px;
background-color: var(--text);
color: var(--bg);
font: inherit;
font-weight: 600;
cursor: pointer;
transition: background-color 0.2s ease;
}
.message-form button:hover {
background-color: var(--accent);
}
.message-form button:focus-visible {
outline: 3px solid var(--accent);
outline-offset: 3px;
}
/* ===== 页脚 ===== */
footer {
text-align: center;
font-size: 0.875rem;
color: var(--muted);
}
/* ===== 响应式：平板（768px 及以上） ===== */
@media (min-width: 768px) {
.world-grid {
grid-template-columns: repeat(2, 1fr);
}
.platforms {
flex-direction: row;
}
.platform-btn {
flex: 1;
}
}
/* ===== 响应式：电脑（1024px 及以上） ===== */
@media (min-width: 1024px) {
.world-grid {
grid-template-columns: repeat(3, 1fr);
}
}检查还有没有漏掉的颜色
在 VS Code 里按 Command + F，在 style.css 里搜索 #。
# 开头的颜色值都只出现在文件最上面的变量定义里，下面的规则里一个都没有。如果还有，把它换成对应的变量。手动切换到街头主题
把 index.html 里的 <body class="theme-gentleman"> 改成 <body class="theme-street">，保存刷新。
切换到泰风主题
再改成 <body class="theme-thai">，保存刷新。
在开发者工具里实时切换
在 Elements 面板里双击 <body class="..."> 的 class 值，直接改成另一个主题名，按回车。
验收演示：改一个变量，整页一起变
在 Elements 里选中 body，在 Styles 里找到当前主题的变量规则（比如 body.theme-street）。点 --accent 的值，改成 #7c3aed（紫色）；再点 --bg 的值，改成 #fdf2f8（浅粉）。
--accent 后，四个平台按钮、输入框聚焦时的边框、发送按钮的悬停色一起变紫；改 --bg 后，整页背景、平台按钮上的文字、输入框背景一起变。刷新页面恢复原样。检查深色主题的可读性
切到街头主题，在 Elements 里选中介绍文字 .tagline，在 Styles 里点 color 值前面的小色块，看弹出面板里的 Contrast ratio（对比度）。
--muted 调亮一些，直到对比度达标。提交并推送
cd ~/code/links
git add index.html style.css
git commit -m "三套主题变量：绅士、街头、泰风；引入 Google Fonts；按钮悬停与过渡"
git pushvar(-accent) 和 var(--acent) 都取不到值。在开发者工具里选中元素，取不到值的变量会显示成灰色或带警告。body .theme-street（中间有空格）。有空格表示“body 里面 class 为 theme-street 的元素”，而不是“class 为 theme-street 的 body”。元素名和 class 要紧挨着：body.theme-street。font-family 里的字体名是否和 Google Fonts 上完全一致，包括大小写和空格，名字里有空格要加引号；最后确认字体的 link 写在 style.css 的 link 前面。transition 写在了 :hover 规则里，或者 transition 里写的属性名和实际变化的属性不一致，比如写了 background 但变化的是 transform。body.theme-street 里有没有 --heading-weight: 400，以及 h1、h2、h3 的规则里是否用了 var(--heading-weight)。用 CSS 变量有什么好处？现场演示：改一个变量，整页颜色一起变。
好处：一是一处定义、多处使用，改一个值所有用到它的地方一起变，不会漏改；二是按用途起名（--bg、--accent），代码读起来就知道这个颜色是干什么的；三是可以在不同元素上重新定义同一个变量，比如在 body.theme-street 里覆盖，只换 body 的 class 就能换一整套主题，HTML 和其他规则都不用改，DAY 20 用 JavaScript 切换风格时也只需要换这个 class；四是整页的颜色、字体、圆角集中管理，风格更统一。
演示：打开开发者工具，选中 body，在 Styles 里找到当前主题的变量规则，把 --accent 改成另一个颜色，四个平台按钮、输入框聚焦边框、发送按钮悬停色一起变；把 --bg 改掉，整页背景也跟着变。
为什么 transition 要写在 .platform-btn 上，而不是写在 .platform-btn:hover 上？
写在元素本身上，无论进入还是离开悬停状态，元素都带着这条过渡规则，所以鼠标移上去和移开时两个方向都是平滑的。如果只写在 :hover 里，鼠标移开时 hover 规则已经不生效了，过渡也跟着消失，按钮会瞬间跳回原样。
绅士主题的标题字体写的是 "Playfair Display", "Noto Serif SC", serif。“三个世界 Three worlds”这样一个中英混排的标题，每个字分别用的是哪款字体？如果访客连不上 Google Fonts 呢？
浏览器逐个字符从左往右找字体。英文字母 Three worlds 在 Playfair Display 里有，就用 Playfair Display；中文“三个世界”在 Playfair Display 里没有，继续往后找，用 Noto Serif SC（思源宋体）。如果连不上 Google Fonts，这两款都没下载到，所有字符都会落到最后的 serif，由系统挑一款衬线字体显示，比如 Mac 上的宋体或 Times。内容不受影响，只是风格打了折扣。
:root 变量、字体栈、clamp()、em 单位、属性选择器和 @keyframes 动画，并用一句中文说出每段在做什么。prefers-reduced-motion 是为谁准备的，并在开发者工具里模拟它。前面四天你一直在“写” CSS：盒模型、Flexbox、Grid、变量和过渡。今天换成“读”。读别人写好的代码，是程序员每天都在做的事，花的时间往往比写还多。你桌面上的 dongge-site 就是一份现成的教材：它完整、上过线，而且讲的就是你自己的三个世界。
官网的 CSS 没有单独的文件，全部写在 index.html 顶部的 <style> 标签里，大约从第 13 行到第 339 行。写在 <style> 里和写在单独的 style.css 里，语法完全一样，区别只是位置。你的链接主页用 <link> 引入外部文件，更适合长期维护；官网为了“一个文件就能打开”，把样式和 HTML 放在了一起。
三百多行 CSS 不要从第一行硬啃到最后一行。推荐按这个顺序读：
:root 里的变量，body 的字体、字号和颜色。它们决定整页的气质。@media 里的规则回答的是“屏幕变窄以后，改了什么”。读的时候一定要配合开发者工具。在浏览器里右键任意元素，选“检查”，右侧 Styles 面板会列出作用在它身上的所有规则。每条规则右上角有一个类似 index.html:93 或 (index):93 的小链接，意思是“这条规则写在第 93 行”。回到 VS Code，按 Ctrl + G 输入行号就能跳过去。
code ~/Desktop/dongge-site 可以用 VS Code 打开整个文件夹。如果提示找不到 code 命令，就在 VS Code 里用“文件 → 打开文件夹”。本页提到的行号以你没改动过的文件为准；如果你 DAY 03 改过文字，行号可能差几行，用 Cmd + F 搜选择器名字更可靠。DAY 09 你学过 CSS 变量。官网把所有颜色和字体都集中放在 :root 里。:root 指的是整个页面最外层的元素，也就是 <html>。变量定义在这里，全页任何地方都能用 var() 取出来。
dongge-site/index.html（第 14–30 行）
:root{
--paper:#F7F6F2;
--paper-2:#EDEBE5;
--ink:#0E0E0E;
--ink-2:#3A3936;
--muted:#7A7872;
--line:#D9D7D0;
--gent:#0F4F37;
--street:#F0521B;
--thai:#B5121F;
--gold:#C9A227;
--serif-en:"Bodoni Moda","Didot","Bodoni 72","Times New Roman",serif;
--serif-cn:"Noto Serif SC","Songti SC","STSong","SimSun",serif;
--sans:"Noto Sans SC","PingFang SC","Hiragino Sans GB","Microsoft YaHei",sans-serif;
--mono:"IBM Plex Mono","SF Mono",Menlo,Consolas,monospace;
color-scheme:light;
}逐行看：
--paper 和 --paper-2 是两种米白的纸色，--ink 是接近纯黑的墨色，--ink-2、--muted、--line 是深浅不同的灰。整页的底色和文字只用这几种中性色，所以看起来干净、统一。--gent、--street、--thai 是三个世界的主色：墨绿、橙红、深红。--gold 是点缀用的金色。主色只用在少数关键位置，才显得有分量。--serif-en 这一行叫“字体栈”。浏览器从左往右找：先用 Bodoni Moda，没有就用 Didot，再没有用 Bodoni 72，再不行用 Times New Roman，最后的 serif 是兜底，意思是“随便给我一个衬线字体”。字体名里有空格时要加引号。--serif-cn 是中文衬线字体（宋体一类），--sans 是中文无衬线字体（黑体一类），--mono 是等宽字体，每个字母一样宽，常用在代码和小标签上。每一栈里都照顾了 Mac 和 Windows 自带的字体，所以换台电脑也不至于太难看。color-scheme:light 告诉浏览器：这一页是浅色设计，表单控件和滚动条也按浅色来画。字体栈里排在最前面的 Bodoni Moda、Noto Serif SC 这些字体，你的 Mac 上默认没有，是从 Google Fonts 下载的。负责下载的是 <head> 里的这一行：
dongge-site/index.html（第 12 行）
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Bodoni+Moda:ital,opsz,wght@0,6..96,400;0,6..96,700;1,6..96,400;1,6..96,700&family=Noto+Serif+SC:wght@600;900&family=Noto+Sans+SC:wght@400;500;700&family=IBM+Plex+Mono:wght@400;500&display=swap">这个网址看起来很长，拆开其实很规整：
family= 后面是字体名，名字里的空格写成 +。要几款字体就写几个 family=，中间用 & 连起来。ital 是斜体（0 正体、1 斜体），wght 是粗细，opsz 是“光学尺寸”，字号不同时字形会微调。比如 Noto+Serif+SC:wght@600;900 的意思是“思源宋体，要 600 和 900 两种粗细”。display=swap 表示：字体还没下载完时，先用字体栈里的备用字体把文字显示出来，下载完再换上，不让访客对着空白等。你觉得官网“有杂志感”，很大一部分来自字体搭配。仔细看会发现，它只给字体安排了三个固定角色。先看两个通用的小工具 class：
dongge-site/index.html（第 46–53 行）
.mono{
font-family:var(--mono);
font-size:11px;
letter-spacing:.18em;
text-transform:uppercase;
color:var(--muted);
}
.it{font-family:var(--serif-en);font-style:italic;font-weight:400}再看页面左上角的品牌名“三岁的东哥 Sansui Dongge”。它的 HTML 是两个 span：
dongge-site/index.html（第 344 行）
<a class="brand" href="#hero"><span class="cn">三岁的东哥</span><span class="en">Sansui Dongge</span></a>dongge-site/index.html（第 68–69 行）
.brand .cn{font-family:var(--serif-cn);font-weight:900;font-size:19px;letter-spacing:.06em}
.brand .en{font-family:var(--serif-en);font-style:italic;font-size:17px}把三段放在一起，三个角色就清楚了：
var(--serif-cn)，粗细 900（最粗一档），字距 .06em。负责“稳”。var(--serif-en) 加 font-style:italic。Bodoni 的斜体笔画细、对比强，负责“贵气”。var(--mono)，11px，全部大写，字距拉开。负责“精致”，很像时装品牌吊牌上的小字。这里有两个新写法要弄懂。第一个是 em 单位：letter-spacing:.18em 里的 em 表示“当前字号的倍数”。字号 11px 时，.18em 就是 11 × 0.18，大约 2px。用 em 的好处是：以后把字号调大，字距会按比例跟着变大，不用改两处。.18 是 0.18 的简写，开头的 0 可以省略。
第二个是 .brand .cn 这种中间带空格的选择器，叫“后代选择器”，意思是“class 为 brand 的元素里面的、class 为 cn 的元素”。这样写，页面别处如果也有 .cn，不会被误伤。
为什么需要它：大标题在电脑上要够大才有气势，但同样的字号放到手机上，会挤成好几行甚至超出屏幕。DAY 08 你用媒体查询在不同宽度下写不同的字号，要写好几段。官网用了一个更省事的函数 clamp()，一行搞定。
dongge-site/index.html（第 93–109 行）
.hero h1{
font-family:var(--serif-cn);
font-weight:900;
font-size:clamp(38px,5.6vw,78px);
line-height:1.18;
letter-spacing:.01em;
margin:0 0 26px;
text-wrap:balance;
}
.hero h1 b{
font-family:var(--serif-en);
font-style:italic;
font-weight:400;
font-size:1.15em;
color:var(--c);
transition:color .6s;
}逐行解释 .hero h1：
font-size:clamp(38px,5.6vw,78px)：clamp 的三个值依次是最小值、理想值、最大值。vw 是“视口宽度的百分之一”，视口就是浏览器里显示网页的那块区域。屏幕 1000px 宽时，1vw 就是 10px。所以理想值 5.6vw 会随屏幕变化，但不会小于 38px，也不会大于 78px。line-height:1.18：行高不带单位，表示“字号的 1.18 倍”。大标题的行高要小，否则两行之间空得像断开了。正文 body 用的是 1.75，标题和正文的行高正好反着来。margin:0 0 26px：四个方向按“上 右 下 左”，只写三个值时，第三个是下，左边跟右边一样。这里只留了 26px 的下外边距。text-wrap:balance：让多行标题每行的长度尽量平均，避免最后一行只剩一个字。这是比较新的属性，老浏览器不认识会直接忽略，不会出错。用三种屏幕算一下 clamp(38px,5.6vw,78px)：
| 屏幕宽度 | 5.6vw 算出来 | 实际字号 |
|---|---|---|
| 375px（手机） | 21px | 38px，被最小值托住 |
| 1000px（笔记本） | 56px | 56px，就用理想值 |
| 1600px（大显示器） | 89.6px | 78px，被最大值压住 |
再看标题里的 <b>。标题的 HTML 是这样的：
dongge-site/index.html（第 358 行）
<h1>在外面是绅士、拳手、潮男，<br>在你面前<b>三岁</b>。</h1>font-size:1.15em：比周围的字大 15%。这里的 em 以 h1 的字号为基准，所以标题怎么缩放，“三岁”都比别的字大一点。color:var(--c) 和 transition:color .6s：颜色来自一个叫 --c 的变量，颜色变化时用 0.6 秒慢慢过渡。--c 是从哪来的？看 hero 区块的开头：
dongge-site/index.html（第 79–85 行）
.hero{
--c:var(--gent);
padding:64px 0 72px;
overflow:hidden;
}
.hero[data-world="street"]{--c:var(--street)}
.hero[data-world="thai"]{--c:var(--thai)}.hero 先把 --c 设成绅士绿。下面两行用的是“属性选择器”：[data-world="street"] 表示“data-world 属性等于 street 的元素”。当 hero 的 data-world 变成 street，--c 就被改成橙色，所有用到 --c 的地方一起变色，还带 0.6 秒过渡。负责改 data-world 的是页面底部的 JavaScript，DAY 20 你会自己写这种切换。今天只要记住一件事：变量可以在某个元素上重新赋值，新值只影响这个元素和它里面的元素。
官网 hero 下面那条黑底白字、一直往左跑的字幕，全部是 CSS 做的，没有用一行 JavaScript。先看 HTML：
dongge-site/index.html（第 382–395 行）
<div class="ticker" aria-hidden="true">
<div class="track">
<span><b>今天陪你玩什么？</b></span><span>What are we playing today?<i>·</i></span>
<span><b>周四</b> 三岁时刻</span><span>Thursday — The three-year-old moment<i>·</i></span>
<span><b>周五</b> 三岁换装</span><span>Friday — One turn, three worlds<i>·</i></span>
<span><b>周日</b> 今天带你去</span><span>Sunday — Come with me<i>·</i></span>
<span><b>22:00</b> 晚安三岁</span><span>Goodnight, three<i>·</i></span>
<span><b>今天陪你玩什么？</b></span><span>What are we playing today?<i>·</i></span>
<span><b>周四</b> 三岁时刻</span><span>Thursday — The three-year-old moment<i>·</i></span>
<span><b>周五</b> 三岁换装</span><span>Friday — One turn, three worlds<i>·</i></span>
<span><b>周日</b> 今天带你去</span><span>Sunday — Come with me<i>·</i></span>
<span><b>22:00</b> 晚安三岁</span><span>Goodnight, three<i>·</i></span>
</div>
</div>注意：中间 5 行写了两遍，一模一样。这不是手误，下面会讲原因。aria-hidden="true" 告诉读屏软件跳过这一块，因为它只是装饰，里面的内容页面别处都有。
dongge-site/index.html（第 183–197 行）
.ticker{
background:var(--ink);color:var(--paper);
overflow:hidden;white-space:nowrap;
border-top:1px solid var(--ink);border-bottom:1px solid var(--ink);
padding:14px 0;
}
.ticker .track{display:inline-block;will-change:transform;animation:tick 40s linear infinite}
.ticker span{
display:inline-block;padding:0 34px;
font-family:var(--serif-en);font-style:italic;font-size:18px;letter-spacing:.02em;
}
.ticker span b{font-family:var(--serif-cn);font-style:normal;font-weight:900;font-size:16px;letter-spacing:.1em}
.ticker span i{color:var(--gold);font-style:normal;padding:0 2px}
@keyframes tick{from{transform:translateX(0)}to{transform:translateX(-50%)}}
@media (prefers-reduced-motion: reduce){.ticker .track{animation:none}html{scroll-behavior:auto}}逐段解释：
overflow:hidden 把超出窗口的部分藏起来；white-space:nowrap 禁止换行，所有文字排成长长的一条。display:inline-block 让它的宽度等于内容的总长度。animation:tick 40s linear infinite 是动画的简写，四个值依次是：用哪段动画（名字叫 tick）、一轮多长（40 秒）、速度曲线（linear 表示匀速）、重复几次（infinite 表示无限）。will-change:transform 提前告诉浏览器“这个元素要移动”，让它准备好画得更流畅。from 是开始时的样子：不移动。to 是结束时的样子：向左移动自己宽度的 50%。translateX 是水平移动，负数往左。b 里改回正体粗宋，分隔用的小圆点放在 i 里染成金色。dongge-site/index.html（第 322–338 行）
@media (max-width:900px){
.wrap{padding:0 20px}
.top nav{display:none}
.hero{padding:40px 0 56px}
.hero .wrap{grid-template-columns:1fr;gap:36px}
.hero-look{justify-self:stretch;max-width:none;order:-1;aspect-ratio:4/5}
.hero .line{min-height:auto}
.switch button{padding-right:18px;font-size:15px}
section.block{padding:64px 0}
.sec-head{grid-template-columns:1fr;gap:10px}
.looks{grid-template-columns:1fr;gap:44px}
.row{grid-template-columns:1fr;gap:6px}
.row .tag{justify-self:start}
.manifesto{grid-template-columns:1fr;gap:36px}
.collab{grid-template-columns:1fr}
footer .grid{grid-template-columns:1fr}
}官网用的是 max-width:900px，意思是“屏幕宽度不超过 900px 时，才用下面这些规则”。这种写法叫“电脑优先”：先按大屏写好，再给小屏打补丁。DAY 08 你学的是反过来的“手机优先”，用 min-width。两种写法都对，读别人的代码时，先看清它用的是哪一种。
挑几条典型的：
.wrap{padding:0 20px}：小屏上两边的留白从 32px 缩到 20px，给内容多留点地方。.top nav{display:none}：手机上放不下顶部导航，直接隐藏。.hero .wrap{grid-template-columns:1fr;gap:36px}：原来是左右两列（文字和大图），变成只有一列。.hero-look 里的 order:-1：让大图排到文字前面，手机上先看到图。.looks{grid-template-columns:1fr}：三个世界从三列变成一列，这和你 DAY 08 做的是同一件事。CSS 的注释写成 /* 注释内容 */，浏览器会完全忽略它。官网已经用 /* ---------- ticker ---------- */ 这样的注释分好了区块，你今天要做的，是在每一段规则上面加一句中文，说清它“管什么、为什么这样写”。加完大概是这样：
dongge-site/index.html（加注释之后）
/* 滚动字幕的窗口：黑底白字，文字排成一行，超出窗口的部分藏起来 */
.ticker{
background:var(--ink);color:var(--paper);
overflow:hidden;white-space:nowrap;
border-top:1px solid var(--ink);border-bottom:1px solid var(--ink);
padding:14px 0;
}
/* 字幕长条：整条匀速向左移动，40 秒一轮，无限循环 */
.ticker .track{display:inline-block;will-change:transform;animation:tick 40s linear infinite}好注释的标准是说“效果和原因”，不要把代码逐字翻译一遍。“把 display 设为 none”是没用的注释；“手机上顶部导航放不下，直接隐藏”才是好注释。
遇到看不懂的一行，先自己猜，再用开发者工具验证：在 Styles 面板里，把那一行属性前面的小勾去掉，等于临时关掉它，看页面哪里变了。这个“关掉看看”的办法，比任何解释都直观，刷新页面就会恢复原样。实在想不通再问 Claude，并且让它先反问你、一步步引导你，不要直接给答案（提示词在本页最后）。
下午你会把三样东西搬到链接主页：字体组合、clamp() 大标题、滚动字幕。明天 DAY 11 专门做手机适配，今天搬过去的东西，都要经得起小屏幕的考验。
打开官网源码和页面
在终端运行下面三行：进入官网文件夹，用 VS Code 打开，再用默认浏览器打开页面。
cd ~/Desktop/dongge-site
code .
open index.html如果你的默认浏览器不是 Chrome，把地址栏里的 file://... 地址复制到 Chrome 里打开。DAY 03 得到的 Vercel 网址也可以，两边内容一样。
用开发者工具点中三个元素
按 Cmd + Option + I 打开开发者工具，再按 Cmd + Shift + C 进入“点选元素”模式，依次点：左上角的“三岁的东哥”、大标题里的“三岁”、滚动字幕里的任意一段文字。每点一个，在 Styles 面板里找到管它的规则，把“选择器 + 行号”记在笔记里。
.hero h1 b 的 color:var(--c)，而 --c 的值来自 .hero。关掉看看
选中滚动字幕，在 Styles 面板里依次取消勾选 .ticker 的 overflow:hidden 和 white-space:nowrap，观察页面怎么变。再选中大标题，取消 font-size，看标题变成什么样。每次观察完，把勾打回去。
white-space:nowrap 后，字幕会折成好几行；去掉 overflow:hidden 后，页面底部会出现横向滚动条。刷新页面，一切恢复。给官网 CSS 写中文注释
在 VS Code 里打开 index.html，从 :root 开始，至少给 15 段规则各写一句中文注释，重点写 hero、ticker 和最后的媒体查询。写完保存，刷新浏览器，页面应该一点都没变。然后提交：
cd ~/Desktop/dongge-site
git add index.html
git commit -m "给官网 CSS 加中文注释"
git pushpush 之后 Vercel 会自动重新部署一次，因为注释不会显示，线上页面看起来不变。
git log --oneline 的第一行是你刚才的提交；打开 GitHub 上的 index.html 能看到你的注释。给链接主页引入官网的字体
切到链接主页项目，用 VS Code 打开：
cd ~/code/links
code .打开 index.html，在 <head> 里、引入 style.css 的那一行上面，加入下面三行。前两行让浏览器提前和 Google Fonts 的服务器“打招呼”，字体下载得更快；第三行是从官网原样复制的字体地址。
links/index.html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Bodoni+Moda:ital,opsz,wght@0,6..96,400;0,6..96,700;1,6..96,400;1,6..96,700&family=Noto+Serif+SC:wght@600;900&family=Noto+Sans+SC:wght@400;500;700&family=IBM+Plex+Mono:wght@400;500&display=swap">如果 DAY 09 你已经引入过别的 Google Fonts，旧的那行可以先留着，两行同时存在也能工作。
在 style.css 里加上字体变量
打开 style.css，在文件最上面你已有的 :root 里加入三个字体变量。如果你想保持旧代码不动，也可以在它下面另写一个 :root，效果一样。
links/style.css
:root{
--serif-en:"Bodoni Moda","Didot","Bodoni 72","Times New Roman",serif;
--serif-cn:"Noto Serif SC","Songti SC","STSong","SimSun",serif;
--mono:"IBM Plex Mono","SF Mono",Menlo,Consolas,monospace;
}做一个会缩放的大标题
在 index.html 里找到显示你名字的 h1，改成下面这样。中文用粗宋，英文名放进 b 里单独一行，用斜体。
links/index.html
<h1 class="big-title">三岁的东哥<b>Sansui Dongge</b></h1>在 style.css 末尾加上：
links/style.css
/* 大标题：中文粗宋，字号在 32px 到 56px 之间跟着屏幕宽度变化 */
.big-title{
font-family:var(--serif-cn);
font-weight:900;
font-size:clamp(32px,8vw,56px);
line-height:1.18;
letter-spacing:.02em;
margin:0 0 16px;
text-wrap:balance;
}
/* 标题里的英文名：另起一行，英文衬线斜体，颜色跟着当前世界走 */
.big-title b{
display:block;
font-family:var(--serif-en);
font-style:italic;
font-weight:400;
font-size:.6em;
color:var(--accent, #0F4F37);
}var(--accent, #0F4F37) 里逗号后面的是“备用值”：如果页面上没有定义 --accent，就用绅士绿。如果你 DAY 09 给三个世界定的主色变量不叫 --accent，把它换成你自己的变量名，这样切换世界时英文名会跟着变色。
加一行等宽小标签
在大标题下面加一行小标签，再把官网的 .mono 搬过来：
links/index.html
<p class="mono">Snooker · BMX · Muay Thai</p>links/style.css
/* 小标签：等宽字体、全大写、字距拉开，像吊牌上的小字 */
.mono{
font-family:var(--mono);
font-size:11px;
letter-spacing:.18em;
text-transform:uppercase;
color:var(--muted, #7A7872);
}加滚动字幕的 HTML
在头像和介绍的下面、平台按钮的上面，加入字幕。内容来自官网的每周节目单，一共 6 段，整段复制成两份：
links/index.html
<div class="ticker" aria-hidden="true">
<div class="track">
<span><b>周一 绅士线</b> Gentleman</span>
<span><b>周二 街头线</b> Street</span>
<span><b>周三 泰风线</b> Thai</span>
<span><b>周四 三岁时刻</b> The three-year-old moment</span>
<span><b>周五 三岁换装</b> One turn, three worlds</span>
<span><b>22:00 晚安三岁</b> Goodnight, three</span>
<span><b>周一 绅士线</b> Gentleman</span>
<span><b>周二 街头线</b> Street</span>
<span><b>周三 泰风线</b> Thai</span>
<span><b>周四 三岁时刻</b> The three-year-old moment</span>
<span><b>周五 三岁换装</b> One turn, three worlds</span>
<span><b>22:00 晚安三岁</b> Goodnight, three</span>
</div>
</div>加滚动字幕的 CSS
在 style.css 末尾加上下面这段。它基本照搬官网，只做了三处改动：加了 width:100%、速度改成 30 秒一轮、字号改小一点适合手机。
links/style.css
/* 滚动字幕的窗口：占满一行，文字不换行，超出部分藏起来 */
.ticker{
width:100%;
background:var(--ink, #0E0E0E);
color:var(--paper, #F7F6F2);
overflow:hidden;
white-space:nowrap;
padding:12px 0;
}
/* 字幕长条：整条匀速向左移动，30 秒一轮，无限循环 */
.ticker .track{
display:inline-block;
will-change:transform;
animation:tick 30s linear infinite;
}
/* 每一段：英文用衬线斜体 */
.ticker span{
display:inline-block;
padding:0 24px;
font-family:var(--serif-en);
font-style:italic;
font-size:16px;
}
/* 每段开头的中文：改回正体粗宋 */
.ticker span b{
font-family:var(--serif-cn);
font-style:normal;
font-weight:900;
font-size:14px;
letter-spacing:.1em;
}
/* 动画：从原位移动到自身宽度的一半，正好接上第二份内容 */
@keyframes tick{
from{transform:translateX(0)}
to{transform:translateX(-50%)}
}
/* 访客开了“减弱动态效果”时，字幕停下来 */
@media (prefers-reduced-motion: reduce){
.ticker .track{animation:none}
}width:100% 是给链接主页特意加的：如果字幕的父元素是一个 align-items:center 的 Flexbox 容器（DAY 07 你很可能这样居中过头像），字幕会按内容长度把自己撑得很宽，整个页面就出现横向滚动条。写上 width:100%，它就只和父元素一样宽。
模拟“减弱动态效果”
在开发者工具里按 Cmd + Shift + P 打开命令菜单，输入 rendering，选择 Show Rendering。在下方出现的 Rendering 面板里找到 Emulate CSS media feature prefers-reduced-motion，选 reduce。
提交链接主页的改动
cd ~/code/links
git status
git add .
git commit -m "加入官网的字体组合、大标题和滚动字幕"如果 git status 提示 not a git repository，说明这个文件夹还没变成仓库，先运行 git init 再执行后面三行。DAY 12 部署时要用到它。
git log --oneline 能看到今天的提交。明天 DAY 11 你会在真手机上打开这个页面，把别扭的地方一个个修掉。link 是不是放在了 <head> 里，网址是否完整复制，中间的 & 一个都不能少。再检查 font-family 里的名字是否和 Google Fonts 上一字不差，比如 "Noto Serif SC" 的大小写和空格。开发者工具 Computed 面板最下面的 Rendered Fonts 会显示实际用上的字体。animation 里写的名字要和 @keyframes 后面的名字完全一样，tick 和 ticker 是两个名字。如果名字没错，看看是不是 Mac 的“系统设置 → 辅助功能 → 显示 → 减弱动态效果”开着，开着的话，你写的那条媒体查询正在生效。.ticker 有 width:100%，而且 overflow:hidden 写在 .ticker 上，不是写在 .track 上。header h1 这类更具体的选择器，把 .big-title 覆盖了。在 Styles 面板里被划掉的那一行，就是被覆盖的规则，顺着它找到是谁赢了。随便指官网上一个元素，说出是哪几行 CSS 让它长成这样。
以 hero 里的平台按钮“小红书”为例。方法是：右键按钮选“检查”，看 Styles 面板列出的规则和行号，再回到 VS Code 对照。
它由三处规则决定：第 139 行 .platforms 让四个按钮用 Flexbox 横排、放不下时换行（flex-wrap:wrap）、间距 8px、去掉列表的小圆点；第 140–145 行 .platforms a 让文字变成 11px 的等宽字体、全大写、字距拉开，并给它 padding:10px 18px 和 1px 的黑色边框，还设置了背景色和文字颜色的过渡；第 146 行 .platforms a:hover 让鼠标移上去时变成黑底白字。
能讲清“哪个选择器、哪几行、各管什么效果”，这题就过了。换成别的元素也一样。
clamp(38px,5.6vw,78px) 在 375px 宽的手机、1000px 宽的笔记本、1600px 宽的显示器上，分别得到多大的字号？
1vw 等于视口宽度的百分之一。375px 时 5.6vw 约等于 21px，小于最小值，所以是 38px；1000px 时正好 56px，在范围内，就是 56px；1600px 时是 89.6px，超过最大值，所以是 78px。
滚动字幕为什么要把内容写两遍，并且移动到 -50%？如果只写一遍会怎样？
写两遍后，长条的总长度是一份内容的两倍。向左移动一半，第二份正好移到第一份原来的位置，这时动画重新开始，画面前后完全一样，所以看不出接缝。
如果只写一遍，文字往左移出窗口后，右边会露出一段空白，接着动画突然回到起点，画面明显“跳”一下。
npx serve 在自己的手机上打开电脑里的链接主页。昨天你把官网的字体、大标题和滚动字幕搬到了链接主页。今天要回答一个更实际的问题：它在手机上好用吗？
链接主页的访客几乎都在手机上。她们在小红书、TikTok、Instagram 上看到你的简介，点一下链接，页面就在手机里打开。电脑上看着再漂亮，手机上别扭，就等于没做好。
手机和电脑有三点根本不同：屏幕窄，一行放不了几个字；用手指点，手指比鼠标指针粗得多；网络时好时坏，大图片会让页面半天出不来。新手页面在手机上最常见的毛病有这几种：
今天上午的每一节，对应解决其中一种。
先讲一段历史。第一代智能手机出现时，网上几乎所有网页都是按电脑屏幕设计的。为了让这些网页在手机上“看起来完整”，手机浏览器想了个办法：假装自己的屏幕有 980px 宽，按这个宽度把页面排好，再整体缩小塞进手机屏幕。结果就是字小得像蚂蚁。
现在的网页是专门为手机设计过的，需要告诉浏览器“别假装了，按你真实的宽度来排”。这就是 <head> 里的这一行，官网里也有：
links/index.html
<meta name="viewport" content="width=device-width, initial-scale=1">name="viewport"：viewport 叫“视口”，就是浏览器里显示网页的那块区域。这行 meta 专门用来设置它。width=device-width：视口的宽度等于设备的宽度。比如某款 iPhone 的宽度是 390，页面就按 390 来排版。initial-scale=1：打开页面时不缩放，1 就是原始大小。你可能会疑惑：iPhone 的屏幕分辨率明明有一千多像素宽，怎么说只有 390？这是因为 CSS 里的 px 不是屏幕上的物理像素点，而是一个“看起来差不多大”的单位。高清屏上 1 个 CSS 像素会用 2 × 2 或 3 × 3 个物理像素来画，所以同样写 16px 的字，在手机上和电脑上看起来差不多大，只是手机上更清晰。
缺了这一行，还有一个连锁反应：你 DAY 08 写的 @media (min-width: 768px) 这类媒体查询，会以为手机有 980px 宽，于是手机上显示的是电脑版布局。
maximum-scale=1 或 user-scalable=no，禁止用户放大页面。不要这样写。视力不好的访客需要用手指放大来看清文字。图片的问题有两种：太宽，把屏幕撑破；比例不对，被挤变形。先解决第一种。在 style.css 最前面加一条对所有图片生效的规则：
links/style.css
img{
max-width:100%;
height:auto;
display:block;
}max-width:100%：图片最宽不超过它的父元素。注意是“最大宽度”，小图片保持原来的大小，不会被拉大。height:auto：宽度被缩小时，高度按原比例一起缩小。如果 HTML 里给图片写了 height 属性，没有这一行图片就会被压扁。display:block：图片默认是行内元素，像文字一样坐在基线上，底下会多出几像素的空隙。改成块级元素，空隙就没了。官网第 44 行也有几乎一样的规则：img{max-width:100%;display:block}。这几乎是每个网站都会写的第一批 CSS。
再解决变形。头像通常要显示成正圆，但你的照片很可能不是正方形，比如手机拍的竖图是 3:4。如果只写 width 和 height 都等于 96px，照片会被硬挤成正方形，人脸变胖。这时要用 object-fit：
links/style.css
.avatar{
width:96px;
height:96px;
border-radius:50%;
object-fit:cover;
margin:0 auto;
}width 和 height 相同：先给头像一个正方形的“相框”。border-radius:50%：圆角半径等于边长的一半，正方形就变成了圆。object-fit:cover：像把照片放进相框一样，保持照片原来的比例，放大到填满整个框，多出来的部分裁掉。官网第 156 行的大图也是这样处理的。margin:0 auto：左右外边距自动平分，让变成块级元素的头像水平居中。HTML 里建议同时写上宽和高，浏览器在图片下载完之前就能先把位置留出来，页面不会因为图片突然出现而“跳”一下：
links/index.html
<img src="avatar.jpg" alt="东哥的头像" width="96" height="96" class="avatar">鼠标指针只有一个像素的尖，手指按下去却是一大片。Apple 的设计规范建议，可以点的东西至少做到 44 × 44 点（在网页里大约就是 44 × 44 的 CSS 像素）。按钮之间还要留出间距，免得点错。
检查方法很简单：在开发者工具里把鼠标移到按钮对应的那行 HTML 上，页面上会浮出一个小标签，显示它的宽和高，比如 a.platform-btn 280 × 36。高度 36 就不够。改法是给按钮一个最小高度：
links/style.css
.platform-btn{
display:flex;
align-items:center;
justify-content:center;
min-height:48px;
padding:12px 20px;
}min-height:48px：高度至少 48px，比 44 稍微宽松一点。用 min-height 而不是 height，是因为文字万一折成两行，按钮还能自己长高。display:flex 加上两个居中：按钮变高之后，文字仍然在正中间。这就是 DAY 07 的 Flexbox 居中。.platform-btn 只是示例名字，你的按钮 class 可能叫别的，下午用开发者工具看一下，换成你自己的。按钮之间的间距，用父元素上的 gap 控制，12px 左右比较舒服。
输入框有一个 iPhone 特有的问题：如果输入框的字号小于 16px，Safari 会在你点进去时自动把整个页面放大，打完字还得自己缩回来，非常烦。解决办法是把表单控件的字号设为 16px：
links/style.css
input,
textarea,
select,
button{
font-size:16px;
font-family:inherit;
}第一行到第四行用逗号隔开，表示这条规则同时作用于四种元素。font-family:inherit 的意思是“继承父元素的字体”。表单控件默认不继承页面字体，会用系统自带的字体，写上这一行，你的留言表单就和页面其他地方的字体统一了。
:hover 效果，在手机上会变成“点一下之后一直停在悬停状态”。如果觉得别扭，可以把 hover 规则包进 @media (hover: hover){ ... } 里，只在有鼠标的设备上生效。页面能左右拖动，是手机适配里最常见、也最伤观感的问题。它的原因只有一个：页面上有某个元素比屏幕宽。常见的“出界”方式有五种：
width:400px，在 320px 宽的手机上必然出界。改成 width:100%;max-width:400px，意思是“尽量占满，但最多 400px”。100vw 在电脑上包含了滚动条的宽度，会比页面多出十几像素。一般写 width:100% 就够了。body 加上 overflow-wrap:break-word，一行放不下时就允许从中间断开。width:100% 再加上左右 padding，总宽度会超过 100%。写上 *{box-sizing:border-box}，让 width 把 padding 和 border 都算进去。官网第 31 行就是这一句。.ticker 没有 width:100%，它会按内容长度把父元素撑宽。怎么找到是哪个元素出界？教你一个临时的调试办法：在 style.css 最后加一行，给所有元素画上红色轮廓线。
links/style.css（临时调试，用完删掉）
*{outline:1px solid red}* 是“通配选择器”，选中页面上所有元素。outline 和 border 很像，但它不占空间，不会改变布局，所以很适合用来“照出”每个盒子的边界。在手机宽度下看一眼，哪个红框的右边伸出了屏幕，就是它。找到并修好之后，记得把这一行删掉。
overflow-x:hidden，把多出来的部分藏起来。它只是把症状盖住了，出界的元素还在，内容可能被切掉一截。先找到原因再修。每改一行就拿手机看一次太慢了。Chrome 开发者工具自带“设备模式”，可以在电脑上模拟手机屏幕。打开开发者工具后按 Cmd + Shift + M，或者点工具栏左上角那个手机和平板叠在一起的图标。
页面上方会出现一条工具栏，常用的有这几个：
建议你固定检查这几个宽度：320（最小的一批手机，例如第一代 iPhone SE）、375（iPhone SE 第二、三代）、390 左右（大多数 iPhone）、430 左右（大屏 iPhone）、768（平板竖屏）。在 320 下没有问题，更宽的屏幕一般也不会有问题。
现在你的页面还在电脑硬盘里，手机访问不到。有一个办法：在电脑上临时开一个“小服务器”，让同一个 Wi-Fi 下的手机通过局域网来访问。DAY 01 你装的 Node.js 自带一个命令 npx，它可以临时下载并运行一个 npm 上的工具，不需要安装。我们用的工具叫 serve：
cd ~/code/links
npx serveNeed to install the following packages ... Ok to proceed? (y)，意思是要先下载 serve，输入 y 回车。Local 是给这台电脑自己用的（localhost 就是“本机”）；Network 是给同一个网络里的其他设备用的，形如 http://192.168.1.23:3000。明天 DAY 12 你会把链接主页部署到 Vercel，到时候任何人在任何地方都能打开。今天先在自己的手机上把它打磨好。
检查 head 里的 viewport
用 VS Code 打开 ~/code/links/index.html，确认 <head> 里有下面这行，并且没有 maximum-scale 或 user-scalable=no。没有就补上，放在 <meta charset="utf-8"> 的下一行。
links/index.html
<meta name="viewport" content="width=device-width, initial-scale=1">做个实验：去掉 viewport 会怎样
在 Chrome 里打开链接主页，按 Cmd + Option + I 打开开发者工具，再按 Cmd + Shift + M 进入设备模式，尺寸选 iPhone SE。然后把 viewport 那行用 HTML 注释包起来，保存并刷新：
<!-- <meta name="viewport" content="width=device-width, initial-scale=1"> -->加两条全局基础规则
在 style.css 的最上面（:root 的下面）加上这两条。如果已经有了，跳过。
links/style.css
*{box-sizing:border-box}
img{
max-width:100%;
height:auto;
display:block;
}
body{
overflow-wrap:break-word;
}如果你原来已经有 body 规则，把 overflow-wrap:break-word; 这一行加进原来的规则里就行。
text-align:center 对它不再起作用。让头像保持正圆
给头像的 img 加上 class="avatar" 和宽高属性，再在 style.css 里写好头像的样式。如果你的头像已经有别的 class，也可以直接把下面几行属性加进原来的规则。
links/index.html
<img src="avatar.jpg" alt="东哥的头像" width="96" height="96" class="avatar">links/style.css
/* 头像：正方形相框 + 圆角变正圆，照片按比例填满，多余部分裁掉 */
.avatar{
width:96px;
height:96px;
border-radius:50%;
object-fit:cover;
margin:0 auto;
}src 要换成你自己头像文件的名字。可以找一张竖拍的照片试试，对比加 object-fit:cover 前后的区别。
在设备模式下逐个宽度检查，列出问题清单
在设备模式里选 Responsive，依次把宽度设成 320、375、390、430、768，每个宽度从上到下看一遍，再试着左右拖动页面。把发现的问题写进手机的备忘录，一条一行，比如“320 宽时页面能左右拖”“平台按钮高度只有 36”“留言框一点就放大”。
用红框找出出界的元素
如果某个宽度下页面能左右拖，在 style.css 最后临时加上这一行，保存并刷新：
links/style.css（临时）
*{outline:1px solid red}在 320 宽度下，把页面往右拖，找到右边伸出屏幕的红框，在开发者工具里点中它，看看是上午讲的五种原因里的哪一种，然后修掉。修完删掉这行红框规则。
把平台按钮做得好点
在开发者工具里点中一个平台按钮，看它的 class 叫什么，再看浮出的小标签上它的高度。然后在 style.css 里找到这个按钮的规则，加上最小高度和居中。下面用 .platform-btn 举例，写的时候换成你自己的 class：
links/style.css
/* 平台按钮：至少 48px 高，手指好点；文字始终在正中间 */
.platform-btn{
display:flex;
align-items:center;
justify-content:center;
min-height:48px;
padding:12px 20px;
}再检查按钮的父元素：它的 gap 如果小于 8px，改成 12px。
让留言表单在 iPhone 上不乱放大
links/style.css
/* 表单控件：字号不小于 16px，避免 iPhone 自动放大；字体跟页面保持一致 */
input,
textarea,
select,
button{
font-size:16px;
font-family:inherit;
}同时检查 textarea：如果你给它写过固定宽度，比如 width:400px，改成 width:100%。
（选做）让悬停效果只在电脑上生效
找到你写过的所有 :hover 规则，把它们移进下面这个媒体查询里。下面以平台按钮为例，里面的颜色写你原来 hover 里的内容：
links/style.css
/* 只有能“悬停”的设备（有鼠标或触控板）才使用 hover 效果 */
@media (hover: hover){
.platform-btn:hover{
background:var(--ink, #0E0E0E);
color:var(--paper, #F7F6F2);
}
}在自己的手机上打开
确认 Mac 和手机连的是同一个 Wi-Fi，然后在终端运行：
cd ~/code/links
npx serve第一次运行时输入 y 同意下载。如果 Mac 弹出“是否允许传入网络连接”，选允许。然后在手机浏览器里输入终端显示的 Network 地址。
用手指把每个地方都试一遍，逐个修掉
在手机上：用大拇指点每个平台按钮，看会不会点错；点进留言框打几个字，看页面会不会放大；把页面左右拖一拖；横过手机再看一遍。新发现的问题补进清单。
然后回到电脑，一条一条修。每修一条，保存文件，在手机上刷新确认，确认好了就在清单上划掉。终端里的 serve 一直开着，不用重启。
提交今天的改动
cd ~/code/links
git add .
git commit -m "手机适配：viewport、图片、点击区域和横向滚动"git status 显示 nothing to commit。明天 DAY 12 是上线日：先请 Claude 审查代码，修完问题后部署到 Vercel。width 和 height 是不是一样大，object-fit:cover 有没有写上。如果还有别的规则也设置了头像尺寸，用开发者工具看看哪条赢了。img{display:block} 之后头像不居中了：块级元素不受父元素 text-align:center 的影响。给头像加 margin:0 auto，或者让父元素用 Flexbox 居中。.message input）把字号又改小了。在最小的手机屏幕上，页面没有横向滚动，每个按钮都好点。
这一题是动手验收，按下面的顺序自己检查：
第一，在设备模式里选 Responsive，宽度填 320，从上到下看完整页，再用鼠标往左右拖，页面不能动。第二，临时加上 *{outline:1px solid red}，确认没有任何红框伸出屏幕右边，看完删掉。第三，把鼠标移到每个平台按钮和提交按钮对应的 HTML 上，浮出的尺寸里高度都不小于 44。第四，用真手机的大拇指把每个按钮点一遍，没有点错。四项都通过就算完成。
如果把 viewport 那行 meta 删掉，手机上打开会怎样？为什么你写的媒体查询也会跟着失灵？
手机浏览器会假装屏幕大约有 980px 宽，按这个宽度排版，再整体缩小塞进屏幕，所以字会很小，要放大才能看。
媒体查询判断的是视口宽度。没有这行 meta，视口宽度就是那个假装的 980px，于是 min-width:768px 这类条件在手机上也成立了，手机显示的是电脑版布局。
为什么通常写 img{max-width:100%}，而不是 img{width:100%}？
width:100% 会强制每张图片都和父元素一样宽，本来只有 96px 的头像或小图标也会被拉大，变得模糊。max-width:100% 只限制“最多多宽”：大图片会缩小到不超出父元素，小图片保持原来的大小。
~/code/links 推到 GitHub，在 Vercel 部署成项目 links，得到一个能放进平台简介的网址。今天是阶段一的最后一天，也是上线日。上午先复习，把零散的知识串起来；再请 Claude 审查代码；下午修完问题就上线。
先对照下面这张表，回忆每一天学的东西在链接主页里用在了哪里。每一行都试着用一句话讲给自己听，讲不出来的，翻回那一天的笔记看一眼。
| 天数 | 学了什么 | 在链接主页里的体现 |
|---|---|---|
| DAY 04 | 标签、属性、嵌套 | 标题、段落、图片、链接 |
| DAY 05 | 语义化标签、表单 | header、main、footer，“给东哥留言”表单 |
| DAY 06 | 选择器、颜色、单位、盒模型 | 按钮的圆角、内边距、外边距 |
| DAY 07 | Flexbox | 头像和名字居中，平台按钮竖排或横排 |
| DAY 08 | Grid、媒体查询 | 三个世界：手机一列、平板两列、电脑三列 |
| DAY 09 | CSS 变量、过渡、Google Fonts | 绅士、街头、泰风三套配色 |
| DAY 10 | 读官网的 CSS | 字体组合、clamp 大标题、滚动字幕 |
| DAY 11 | 手机适配 | viewport、正圆头像、点击区域、没有横向滚动 |
复习时有一个好方法：合上笔记，拿一张白纸，凭记忆画出链接主页的结构，标出每一块用了哪个标签、哪种布局。画不出来的地方，就是你今天要回去补的地方。
为什么需要清单：上线前人容易兴奋，也容易漏。飞行员起飞前要逐项过检查单，不是因为他们不会开飞机，而是因为靠记忆一定会漏。下面这份清单分四类，每一项都能用“是”或“否”回答。
HTML
<html lang="zh-CN"> 写了吗？它告诉浏览器和读屏软件这是中文页面。<head> 里有 charset、viewport、<title> 和一句 <meta name="description"> 吗？title 和 description 会出现在搜索结果和分享卡片里。<h1> 吗？标题层级有没有跳级，比如 h2 下面直接是 h4？alt 吗？头像写“东哥的头像”，纯装饰的图片写 alt=""。<a>，页面上执行动作用 <button>，没有用 div 冒充按钮吧？<label> 吗？CSS
:focus-visible）吗？用 Tab 键在页面上走一遍，能看出当前停在哪个按钮上。最后一项多解释一句。有些访客不用鼠标，而是用键盘的 Tab 键在链接和按钮之间跳。浏览器默认会给当前聚焦的元素画一圈轮廓，但很多人为了好看，写了 outline:none 把它去掉，这些访客就不知道自己停在哪了。官网第 43 行的写法值得照搬：
dongge-site/index.html（第 43 行）
a:focus-visible,button:focus-visible{outline:2px solid var(--ink);outline-offset:3px}:focus-visible 是一种“伪类”，和 :hover 类似，表示“用键盘聚焦到这个元素时”。用鼠标点击时它通常不会出现，所以不影响观感。outline-offset:3px 让轮廓离元素远 3px，看起来更清楚。
链接
https://example.com/... 占位地址，都换成了你自己的真实主页吗？target="_blank" rel="noopener" 吗？前者让它在新标签页打开，后者是安全设置，防止新页面反过来操控你的页面。文件
index.html，并且在项目文件夹最外层吗？avatar.jpg、style.css），而且大小写和真实文件名一模一样吗？这一条下一节专门讲。新手第一次部署，最常见的意外是：自己电脑上一切正常，上线后图片裂了，或者样式全没了。十有八九是这两个原因。
第一，文件名大小写。Mac 的文件系统默认不区分大小写，你把图片存成 Avatar.JPG，HTML 里写 avatar.jpg，Mac 照样能找到。但 Vercel 的服务器区分大小写，在它看来这是两个不同的文件，于是返回 404，图片就裂了。
links/index.html（错误示范）
<!-- 真实文件名是 Avatar.JPG，这里写成小写，Mac 上正常，上线后 404 -->
<img src="avatar.jpg" alt="东哥的头像" width="96" height="96" class="avatar">最省心的做法是给自己定一条规矩：文件名一律用小写英文字母、数字和短横线，比如 avatar.jpg、look-street-01.jpg。不用中文、不用空格、不用大写。
第二，绝对路径。如果你曾经把图片直接拖进 VS Code，路径可能变成了 /Users/dong/code/links/avatar.jpg 这样的完整路径。它只在你自己的电脑上存在，服务器上根本没有 /Users/dong 这个文件夹。要改成相对路径 avatar.jpg，意思是“和 index.html 在同一个文件夹里”。
怎么检查：在终端里用 ls 看真实文件名，再用 grep 把 HTML 里所有引用文件的地方列出来，一一对照。
cd ~/code/links
ls
grep -n 'src=\|href=' index.htmlgrep -n 会显示匹配到的每一行和行号。'src=\|href=' 的意思是“包含 src= 或者 href= 的行”，中间的 \| 表示“或者”。
除了自己看，还可以让工具帮你查出肉眼看不到的错误。
W3C 验证器是制定 HTML 标准的组织提供的免费检查工具。打开 validator.w3.org，选 Validate by File Upload，上传你的 index.html，它会列出所有不符合标准的地方，比如标签没闭合、属性写错、同一个 id 用了两次。Error 是必须改的，Warning 是建议，逐条看一看。
开发者工具的 Console 面板会显示页面加载时出的错。打开开发者工具，点 Console 标签，再刷新页面。如果有红色的 Failed to load resource: ... 404，说明某个文件没找到，后面跟着的就是那个文件的地址。上线前 Console 应该干干净净，一行红字都没有。
这一阶段 Claude 的角色是“老师”。老师批改作业，会用红笔圈出问题、写上为什么错，但不会替你重写一遍。如果让 Claude 直接改，你得到的是一份更好的代码，却错过了这次最好的学习机会：自己找到原因、自己修好。
一段好的审查提示词包含四样东西：
限定“最多 10 条”很重要：问题太多你会不知道从哪下手，先把最重要的修掉。审查结果出来后，不是每一条都必须照做。你可以追问“为什么这条是问题”，也可以在想清楚之后决定不改。审稿人的意见是参考，决定权在你。
拿到的结果大概会是这样的一条：
index.html 第 18 行，必须改：头像图片没有 alt 属性。读屏软件会把文件名念出来，图片加载失败时也没有文字替代。
处理每一条时，按三步走：先在文件里找到那一行，确认问题真的存在；再用自己的话说出“为什么这是问题”，说不出来就追问 Claude；最后自己动手改，改完刷新页面确认效果。如果某一条你想清楚了决定不改，比如它建议换一种配色，而你就是喜欢现在的颜色，在清单上写一句不改的理由，这也是一种判断力的练习。
DAY 03 你已经把旧官网部署过一次，今天的流程完全一样，只是换了一个项目。再把这条链路理一遍：
main 分支有新的提交，就自动把代码取下来，发布到全球的服务器上。链接主页是纯 HTML 和 CSS，不需要“构建”这一步，所以导入 Vercel 时，Framework Preset 选 Other，构建命令留空，Vercel 会把文件原样发布出去。
部署之后，你的日常流程就变成：改代码、commit、push，等几十秒，网站自动更新。推送到 main 分支的会成为正式版本（Production）；以后如果你在别的分支上提交，Vercel 会生成一个单独的预览网址（Preview），不影响正式网站。
项目名我们统一叫 links。Vercel 会给你一个 .vercel.app 结尾的免费网址。如果 links.vercel.app 已经被别人占了，网址会自动带上一段后缀，以页面上显示的为准。
拿到网址后，你可以把它放进各个平台的个人简介。每个平台对简介里能不能放链接、放几个、需要什么条件，规则都不一样，也会调整，以平台当时的规定为准。放之前先在自己手机上把每个按钮都点一遍，确认都能跳到你真实的主页。
今晚的验收是：不看教程，30 分钟内从零写出一个居中的名片页。它考的是这一阶段最核心的三件事：HTML 骨架、盒模型、Flexbox 居中。建议你写之前先在纸上列出步骤：
charset 和 viewport。body 至少和屏幕一样高，再用 Flexbox 把卡片放到正中间。从明天 DAY 13 开始，你要学编程语言 JavaScript。HTML 是骨架，CSS 是衣服，JavaScript 让页面能“动”起来，能响应访客的点击和输入。
按清单自查一遍
打开 ~/code/links 里的 index.html 和 style.css，对照上午的检查清单逐项检查。在手机备忘录里记下每一项的结果，“否”的那几项就是你要修的问题。
检查文件名和路径
cd ~/code/links
ls
grep -n 'src=\|href=' index.html逐行对照：HTML 里写的每个文件名，大小写是否和 ls 显示的一模一样？有没有以 /Users/ 开头的路径？文件名里有没有大写、中文或空格？有的话，把文件改名并同步修改 HTML。在终端里改名用 mv，比如 mv Avatar.JPG avatar.jpg。
用 W3C 验证器检查 HTML
打开 https://validator.w3.org/，点 Validate by File Upload，选择 ~/code/links/index.html，点 Check。
从第一条 Error 开始，看它说的是第几行（Line）、什么问题，在 VS Code 里修掉，保存，重新上传检查。
检查 Console 里有没有红字
用 Chrome 打开 index.html，按 Cmd + Option + J，这个快捷键会直接打开开发者工具的 Console 面板。按 Cmd + R 刷新页面。
请 Claude 审查，只列问题
在 Claude Code 里打开 ~/code/links 这个文件夹，新开一个对话，把本页最后“问 Claude”部分的第一条提示词发给它。如果 Claude 请求编辑文件，点拒绝。
拿到问题列表后，把它复制到备忘录，和你自查的结果合并成一份“待修清单”。看不懂的条目，追问“为什么这是个问题”，而不是“帮我改”。
逐条修改，每修一类提交一次
从“必须改”的开始。每修完一条，保存、刷新浏览器确认效果、在清单上划掉。同一类问题修完后提交一次，这样以后翻历史记录也清楚：
git add .
git commit -m "修复：给所有图片补上 alt"提交说明写清这一次修了什么。修完一轮后，可以把你的改动发给 Claude，只问“这样修对不对”，让它确认，但不让它改。
git log --oneline 能看到今天好几条“修复：……”的提交，待修清单里“必须改”的全部划掉了。换上你真实的平台主页地址
先找出还在用占位地址的地方：
grep -n "example.com" index.html在小红书、TikTok、Facebook、Instagram 里分别打开你自己的主页，复制主页链接，替换对应按钮 href 里的 https://example.com/...。同时确认每个外部链接都带着 target="_blank" rel="noopener"。
确认 Git 状态干净
cd ~/code/links
git status
git log --oneline如果 git status 提示 not a git repository，先运行 git init，再 git add . 和 git commit -m "链接主页：首次纳入 Git 管理"。如果列出了还没提交的改动，先提交。
git status 显示 nothing to commit, working tree clean，并且当前分支是 main。推到 GitHub
和 DAY 03 推旧官网一样，用 GitHub 命令行工具建仓库并推送：
gh repo create links --private --source=. --remote=origin
git push -u origin main
gh repo view --web第一行在你的 GitHub 账号下新建一个叫 links 的私有仓库，并把它设为这个文件夹的远程仓库 origin。第二行把 main 分支推上去，-u 让以后直接写 git push 就行。第三行在浏览器里打开这个仓库。
在 Vercel 导入 links 仓库并部署
打开 https://vercel.com/new（或在控制台点 Add New… 再选 Project）。在 Import Git Repository 列表里找到 links，点旁边的 Import。如果列表里没有它，多半是 DAY 03 你只给 Vercel 授权了 dongge-site 这一个仓库：点列表下方调整 GitHub 权限的链接，在 Repository access 里把 links 也勾上，保存后回到 Vercel 刷新。
在配置页面：
links。./，因为 index.html 就在仓库最外层。点 Deploy。界面文字可能随 Vercel 更新有变化，以实际页面为准。
在手机上把线上版本完整测一遍
用手机浏览器打开你的网址，按这个顺序测：页面是否正常显示、字体是否加载、滚动字幕是否在跑、头像是否是正圆、能不能左右拖动、四个平台按钮是否都跳到你真实的主页、留言框点进去会不会放大。再在电脑上打开，按 Cmd + Option + J 看 Console 有没有红字。
改一行字，体验自动更新，并记下网址
把介绍文字改一个词，然后：
git add .
git commit -m "微调介绍文字"
git push打开 Vercel 项目的 Deployments 页面，看到新部署从 Building 变成 Ready 后，刷新手机上的网页，确认改动已经上线。最后把网址记进学习笔记：
cd ~/code/learn
echo "链接主页已上线：把这里换成你的网址" >> git-notes.md
git add git-notes.md
git commit -m "记录链接主页的线上地址"
git push运行前把引号里的文字换成你真实的网址。要不要现在就放进各平台的简介，由你自己决定。
git-notes.md 的最后一行是链接主页的网址。今晚做完验收第 1 题，阶段一就完成了。/Users/... 开头的绝对路径。用 ls 和 grep -n 'src=' index.html 对照，改好后重新 commit 和 push。index.html（比如叫 Index.html 或 links.html），或者它不在仓库最外层。在 GitHub 仓库页面上确认 index.html 出现在第一层文件列表里。gh repo create 提示仓库名已存在或 remote origin already exists：说明你之前已经建过这个仓库，或者这个文件夹已经有远程地址了。用 git remote -v 看当前的远程地址，如果已经指向 github.com/你的用户名/links，直接 git push -u origin main 就行。不看教程，30 分钟内从零写出一个居中的名片页。
写完之后再对照。你的写法不必一模一样，关键是：有完整骨架和 viewport；卡片在屏幕正中间；窄屏上不溢出。下面把 CSS 写在 <style> 里，一个文件就能打开，存成 ~/code/learn/card.html。
learn/card.html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>三岁的东哥 · 名片</title>
<style>
*{box-sizing:border-box}
body{
margin:0;
min-height:100vh;
display:flex;
align-items:center;
justify-content:center;
padding:16px;
background:#F7F6F2;
color:#0E0E0E;
font-family:"PingFang SC",sans-serif;
}
.card{
width:100%;
max-width:360px;
padding:32px 24px;
background:#FFFFFF;
border:1px solid #D9D7D0;
border-radius:16px;
text-align:center;
}
.card h1{margin:0 0 8px;font-size:28px}
.card p{margin:0 0 24px;color:#3A3936}
.card a{
display:block;
margin-top:12px;
padding:12px;
border:1px solid #0E0E0E;
border-radius:999px;
color:inherit;
text-decoration:none;
}
</style>
</head>
<body>
<main class="card">
<h1>三岁的东哥</h1>
<p>在外面是绅士、拳手、潮男，在你面前三岁。</p>
<a href="https://example.com/xiaohongshu" target="_blank" rel="noopener">小红书</a>
<a href="https://example.com/tiktok" target="_blank" rel="noopener">TikTok</a>
</main>
</body>
</html>居中靠的是 body 上的三行：display:flex 让 body 成为 Flexbox 容器，justify-content:center 让卡片在主轴（水平方向）居中，align-items:center 让它在交叉轴（垂直方向）居中。min-height:100vh 让 body 至少和屏幕一样高，否则 body 只有卡片那么高，垂直居中看不出效果。卡片用 width:100% 加 max-width:360px，在手机上占满、在电脑上不超过 360px。示例链接记得换成你自己的主页。
链接主页在你的 Mac 上图片一切正常，部署到 Vercel 后图片裂了。最可能的原因是什么？你会怎么查？
最可能是文件名大小写不一致：Mac 默认不区分大小写，Vercel 的服务器区分，Avatar.JPG 和 avatar.jpg 在服务器上是两个文件。第二可能是用了 /Users/... 开头的绝对路径，服务器上没有这个位置。
查法：在线上页面打开 Console，看 404 报错里是哪个文件地址；再在终端用 ls 看真实文件名，用 grep -n 'src=' index.html 看 HTML 里写的路径，两边逐字对照。
你改了一行字并执行了 git push，从这一刻到手机上看到新内容，中间发生了什么？
push 把你本地的新提交上传到 GitHub 的 links 仓库。Vercel 和这个仓库是连着的，发现 main 分支有新提交，就自动取下最新的代码开始部署；因为是纯静态文件，不用构建，直接发布到它的服务器上，这次部署成为新的正式版本。手机再次请求网址时，拿到的就是新文件。你全程没有手动上传任何文件。
node 文件名.js 在终端里运行一个 .js 文件。let 和 const 声明变量，说出两者的区别，并知道什么时候该用哪个。typeof 检查一个值的类型。"5" + 3、"5" - 3 这类表达式的结果，并用 Number() 把文字变成数字。阶段一你学了 HTML 和 CSS：HTML 是网页的骨架，CSS 是衣服。但它们都是“静止”的，页面写成什么样就是什么样。从今天开始学的 JavaScript（简称 JS）是一门编程语言，它让页面能“动”起来：访客点了按钮，页面换一种风格；填完表单，页面显示一句感谢。你旧官网最底下那段 <script>，每隔几秒自动切换三个世界，就是 JavaScript 写的。
接下来六天，你先不碰网页，只学 JavaScript 语言本身：变量、条件、循环、函数、数组、对象。就像学开车先在练车场练基本操作，再上路。上午的阅读材料是“现代 JavaScript 教程”（zh.javascript.info）的“JavaScript 基础知识”一章，本页讲的内容和它的前半部分对应，本页最后有链接。
JavaScript 可以在两个地方运行：
> 后面输入代码，按回车就会运行。适合试一两行代码。node 文件名.js。适合写成段的程序。今天最重要的一行代码是 console.log()，它的作用是“把括号里的东西显示出来”。在控制台里输入下面三行（可以一次粘贴进去）：
console.log("你好，我是三岁的东哥");
console.log(1 + 2);
console.log("1 + 2");运行结果：
你好，我是三岁的东哥
3
1 + 2注意第二行和第三行的区别：没有引号的 1 + 2 是一道算术题，JavaScript 会算出 3；加了引号的 "1 + 2" 是一段文字，原样显示。每一行末尾的分号 ; 表示“这句话说完了”，养成每句都写分号的习惯。
allow pasting 再回车。这是为了防止有人骗你粘贴恶意代码，照做一次就好。另外，控制台在 console.log 的结果下面常会多显示一行灰色的 undefined，那是 console.log 自己的“返回值”，现在可以忽略，DAY 15 学函数时你就明白了。用 Node 运行文件也很简单。在终端里建好练习文件夹和第一个文件：
mkdir -p ~/code/learn/js
cd ~/code/learn/js
touch hello.js
code hello.js在 VS Code 里写入下面的内容并保存：
learn/js/hello.js
// 这是注释，JavaScript 会跳过它，写给人看的
console.log("第一次用 Node 运行 JavaScript");
console.log(6 * 4);回到终端运行 node hello.js：
运行结果：
第一次用 Node 运行 JavaScript
24以 // 开头的是单行注释，和 CSS 的 /* */ 一样，是写给人看的说明，程序会跳过它。JavaScript 里也可以用 /* */ 写多行注释。
为什么需要变量：程序要记住很多东西，比如粉丝数、今天是哪个世界、访客的昵称。变量就像一个贴了标签的收纳盒，盒子里放数据，标签上写名字。以后想用这个数据，喊标签名就行。
let followers = 1200;
console.log(followers);
followers = 1350;
console.log(followers);
followers = followers + 100;
console.log(followers);运行结果：
1200
1350
1450逐行解释：
let followers = 1200;：let 表示“我要新建一个变量”，followers 是标签名，= 表示“把右边的值放进左边的盒子”，1200 是放进去的值。注意这里的 = 不是数学里的“等于”，而是“赋值”，也就是“放进去”。console.log(followers);：括号里写的是变量名，没有引号，所以显示的是盒子里的值 1200，而不是 followers 这几个字母。followers = 1350;：换一个值放进去。盒子已经建好了，不用再写 let。followers = followers + 100;：先算等号右边，取出现在的值 1350 加上 100，得到 1450，再放回盒子里。另一种声明方式是 const，它是 constant（常量）的缩写。用 const 声明的变量，贴上标签后就不能再换成别的值：
const brand = "三岁的东哥";
console.log(brand);运行结果：
三岁的东哥如果你试图给它换一个值：
const platform = "小红书";
platform = "TikTok";控制台会显示红色的报错：Uncaught TypeError: Assignment to constant variable.，意思是“不能给常量重新赋值”。Node 里显示的是同样的 TypeError: Assignment to constant variable.，前面没有 Uncaught。
该用哪个？记住一条规则：默认用 const，确定这个值以后要变，才用 let。品牌名、平台名这种不会变的用 const；粉丝数、当前第几题这种会变的用 let。这样读代码的人一眼就知道哪些值会变，程序也不容易被意外改坏。
你在网上的老教程里还会看到 var，它是 JavaScript 早期声明变量的方式，有一些容易出错的怪脾气（DAY 15 讲作用域时会提到）。现在的代码不再用它，你也不要用。
变量名有几条硬性规则：只能包含字母、数字、_ 和 $；不能以数字开头；不能用 let、const 这类 JavaScript 自己的关键字；区分大小写，followers 和 Followers 是两个变量。除此之外还有两条好习惯：
| 好名字 | 不好的名字 | 原因 |
|---|---|---|
followerCount | a | 名字要说清楚里面装的是什么 |
worldName | world_name_string | JavaScript 习惯用“小驼峰”：第一个单词小写，后面每个单词首字母大写 |
birthYear | 2world | 数字开头直接报错 |
同一个变量名只能声明一次。先写了 let followers = 1;，再写 let followers = 2;，会报错 SyntaxError: Identifier 'followers' has already been declared，意思是“这个名字已经被用过了”。
为什么要分类型：数字可以做加减乘除，文字可以拼接，“是或否”可以用来做判断。JavaScript 必须知道一个值是什么类型，才知道能对它做什么。JavaScript 一共有 8 种类型，今天先学最常用的 5 种：
28、3.5、-10。整数和小数都是 number。"街头"。true（是）和 false（否）。另外三种是 bigint（特别大的整数）、symbol（很少用）和 object（对象，DAY 16 和 DAY 17 会学）。用 typeof 可以查看一个值的类型：
console.log(typeof 28);
console.log(typeof 3.5);
console.log(typeof "街头");
console.log(typeof true);
console.log(typeof undefined);
console.log(typeof null);运行结果：
number
number
string
boolean
undefined
object最后一行 typeof null 得到 object，这是 JavaScript 诞生时留下的一个老错误，为了不让旧网站出问题，一直没有改。记住它是个特例就行。
number 的两个小怪癖。先看代码：
console.log(0.1 + 0.2);
console.log("街头" * 2);
console.log(typeof NaN);运行结果：
0.30000000000000004
NaN
number第一行：计算机用二进制存小数，有些小数存不精确，所以 0.1 + 0.2 会多出一点点。几乎所有编程语言都这样，算钱的时候要特别小心。第二行：文字没法乘以 2，结果是 NaN，意思是 Not a Number，“不是一个数字”。有趣的是，第三行显示 NaN 自己的类型却是 number。
string 的三种引号。单引号 '街头' 和双引号 "街头" 完全一样。第三种是反引号 `（键盘左上角 1 左边那个键，输入法要切到英文），它写出来的叫“模板字符串”，可以用 ${ } 把变量直接嵌进文字里：
const world = "泰风";
const feeling = "被保护感";
console.log("今天是" + world + "线");
console.log(`今天是${world}线，给你${feeling}。`);
console.log("三岁的东哥".length);运行结果：
今天是泰风线
今天是泰风线，给你被保护感。
5第三行用 + 把几段文字连起来，叫“拼接”。第四行用模板字符串，效果一样，但更好读，不用数加号和引号。以后拼句子，优先用模板字符串。最后一行的 .length 能取出字符串有几个字符，“三岁的东哥”是 5 个字。
undefined 和 null 都表示“没有”，但来源不同：
let nickname;
console.log(nickname);
let answer = null;
console.log(answer);运行结果：
undefined
null打个比方：undefined 是盒子贴好了标签，但你还没往里放任何东西，是 JavaScript 自动给的“没有”；null 是你亲手往盒子里放了一张写着“空”的纸条，是你主动说“这里没有”。后面做粉丝提问箱时，“昵称可以不填”“回答还没写”这种情况，就会用 null 来表示。
运算符就是 +、- 这类符号，用来对值做计算或比较。先看算术运算符，用你的更新计划举例：
const videosPerWeek = 6;
const weeks = 4;
console.log(videosPerWeek * weeks);
console.log(10 / 3);
console.log(10 % 3);
console.log(2 ** 10);
console.log((2 + 3) * 4);运行结果：
24
3.3333333333333335
1
1024
20* 是乘，/ 是除。一周 6 条、4 周就是 24 条。% 是“取余数”：10 除以 3 商 3 余 1，所以结果是 1。它看起来没什么用，其实很常用，比如判断一个数是不是偶数（除以 2 余数为 0），明天的 FizzBuzz 就靠它。** 是乘方，2 ** 10 就是 2 的 10 次方。给变量“在原来的基础上改一改”，有几种简写：
let likes = 99;
likes += 1;
console.log(likes);
likes++;
console.log(likes);
likes -= 10;
console.log(likes);
likes *= 2;
console.log(likes);运行结果：
100
101
91
182likes += 1 是 likes = likes + 1 的简写，-=、*= 同理。likes++ 是“加 1”的最短写法，明天写循环时会天天用到。
比较运算符用来比较两个值，结果一定是 boolean，也就是 true 或 false：
console.log(28 > 18);
console.log(28 <= 18);
console.log(5 === 5);
console.log(5 === "5");
console.log(5 == "5");
console.log("小红书" !== "TikTok");运行结果：
true
false
true
false
true
true>、<、>=、<= 和数学里一样。重点是“等于”：JavaScript 里有三个长得很像的符号，一定要分清：
=：一个等号是赋值，“把右边放进左边”。===：三个等号是“严格相等”，值和类型都一样才是 true。数字 5 和文字 "5" 类型不同，所以是 false。==：两个等号是“宽松相等”，比较前会偷偷把类型转换成一样的，所以 5 == "5" 是 true。这种偷偷转换经常带来意想不到的结果。规则很简单：永远用 === 和 !==（后者是“严格不等于”），不要用 == 和 !=。
当你让不同类型的值一起运算时，JavaScript 会自动转换类型，这叫“隐式转换”。这是新手最容易踩的坑，也是今晚验收的原题。先看结果：
console.log("5" + 3);
console.log("5" - 3);
console.log("5" * "2");
console.log("三岁" - 1);
console.log(1 + 2 + "3");
console.log("1" + 2 + 3);运行结果：
53
2
10
NaN
33
123规律只有一条：+ 有两个身份，其他算术运算符只有一个。
+ 既能做加法，也能拼接文字。只要两边有一个是字符串，它就当拼接用：把 3 也变成文字 "3"，拼成 "53"。-、*、/ 只能做数学运算，所以会把字符串转成数字再算："5" 变成 5，5 - 3 得 2。1 + 2 + "3" 先算 1 + 2 得 3，再和 "3" 拼接得 "33"；"1" + 2 + 3 一开始就是拼接，得到 "12"，再拼上 3 得到 "123"。注意：console.log 显示字符串时不带引号，所以 "53" 和 53 看起来一样。想确认类型，用 typeof：
console.log(typeof ("5" + 3));
console.log(typeof ("5" - 3));运行结果：
string
number与其让 JavaScript 偷偷转换，不如自己明确地转，这叫“显式转换”：
console.log(Number("28"));
console.log(Number("28岁"));
console.log(Number(""));
console.log(Number(true));
console.log(String(28) + 1);
console.log(parseInt("28岁"));运行结果：
28
NaN
0
1
281
28Number() 把值转成数字。整个字符串必须都是数字才行，"28岁" 里有汉字，得到 NaN。空字符串会变成 0，true 变成 1。String() 把值转成字符串，转完再 + 1 就是拼接，得到 "281"。parseInt() 更宽松：从头开始读，读到不是数字的地方就停，所以 "28岁" 能读出 28。为什么这件事很重要？DAY 21 你会从网页的输入框里读取访客填的内容，输入框给你的永远是字符串，哪怕访客填的是数字：
const inputValue = "1200";
console.log(inputValue + 300);
console.log(Number(inputValue) + 300);运行结果：
1200300
1500最后说一种明天要用的转换：转成 boolean。明天写 if 判断时，JavaScript 会把条件自动转成 true 或 false。只有 6 个值会变成 false：false、0、""（空字符串）、null、undefined、NaN，它们叫“假值”。其他所有值都是“真值”，包括 "0" 和只有一个空格的 " "：
console.log(Boolean(0));
console.log(Boolean(""));
console.log(Boolean("0"));
console.log(Boolean("东哥"));
console.log(Boolean(null));运行结果：
false
false
true
true
false最后把今天学的放在一起，写一个自我介绍程序。在 ~/code/learn/js/ 里新建 day13-intro.js：
learn/js/day13-intro.js
// 自我介绍：把几个变量拼成一句话
const name = "东哥";
const birthYear = 1998; // 换成你自己的出生年份
const currentYear = 2026;
const age = currentYear - birthYear;
const sports = "斯诺克、BMX、泰拳";
const intro = `我是${name}，今年${age}岁，平时在${sports}三个世界里切换。`;
console.log(intro);
console.log(`这句话一共 ${intro.length} 个字符。`);在终端运行 node day13-intro.js：
运行结果：
我是东哥，今年28岁，平时在斯诺克、BMX、泰拳三个世界里切换。
这句话一共 32 个字符。逐行看：前五行都用 const，因为这些值在程序运行期间都不会变。age 不是直接写死的，而是用两个年份相减算出来的，明年只要改 currentYear 一处，年龄就自动对了。intro 用模板字符串把四个变量嵌进一句话。最后一行在模板字符串里又用了 intro.length，${ } 里不仅能放变量，还能放任何能算出值的表达式。
今天你学会了让程序“记住”数据和“计算”数据。明天 DAY 14 学条件和循环，程序就能“做决定”和“重复做事”了。
准备练习文件夹
确认 Node 可用，并用 VS Code 打开练习文件夹。上午已经建过 js 文件夹的话，mkdir -p 不会重复创建，也不会报错。
node -v
mkdir -p ~/code/learn/js
cd ~/code/learn/js
code .node -v 显示一个以 v 开头的版本号，比如 v24.x.x，具体数字以你安装的为准；VS Code 打开了 js 文件夹，里面有上午写的 hello.js。练习 1 到 3：在控制台里热身
打开 Chrome，按 Cmd + Option + J 打开控制台，完成下面三题。第 2、3 题要先在纸上写下你的预测，再运行对答案。
练习 1：声明一个常量 brand，值是“三岁的东哥”；声明一个变量 followers，值是 800。给 followers 加 200，然后用一行 console.log 同时显示两个变量。
练习 2：预测这五个表达式的结果："5" + 3、"5" - 3、true + 1、"3" * "4"、1 + "1" - 1。
练习 3：预测这五个 typeof 的结果：typeof "28"、typeof 28、typeof null、typeof undefined、typeof NaN。
提示：console.log 的括号里可以放好几个值，用逗号隔开，显示时中间会自动加一个空格。true 参与数学运算时会变成 1。
// 练习 1
const brand = "三岁的东哥";
let followers = 800;
followers += 200;
console.log(brand, followers);
// 练习 2
console.log("5" + 3);
console.log("5" - 3);
console.log(true + 1);
console.log("3" * "4");
console.log(1 + "1" - 1);
// 练习 3
console.log(typeof "28");
console.log(typeof 28);
console.log(typeof null);
console.log(typeof undefined);
console.log(typeof NaN);运行结果：
三岁的东哥 1000
53
2
2
12
10
string
number
object
undefined
number最容易错的是 1 + "1" - 1：从左往右，先 1 + "1" 拼接成 "11"，再 "11" - 1，减号把 "11" 转成数字 11，得到 10。如果控制台提示 Identifier 'brand' has already been declared，说明你之前在这个页面声明过 brand，刷新页面再粘贴。
练习 4：摄氏度转华氏度
新建 day13-temperature.js。曼谷今天 33°C，算出相当于多少华氏度，并输出一句完整的话。公式：华氏度 = 摄氏度 × 9 ÷ 5 + 32。
提示：先用一个 const 存摄氏度，再用一个 const 存算出来的华氏度，最后用模板字符串输出。° 这个符号可以直接复制题目里的。
learn/js/day13-temperature.js
const celsius = 33;
const fahrenheit = celsius * 9 / 5 + 32;
console.log(`曼谷今天 ${celsius}°C，相当于 ${fahrenheit}°F。`);运行结果：
曼谷今天 33°C，相当于 91.4°F。练习 5：华氏度转摄氏度，体会括号的作用
在同一个文件末尾继续写。伦敦今天 59°F，算出相当于多少摄氏度。公式：摄氏度 = (华氏度 − 32) × 5 ÷ 9。写完后，故意再写一个不加括号的版本，对比两个结果。
提示：变量名不能和上一题重复，可以叫 londonF、londonC。
const londonF = 59;
const londonC = (londonF - 32) * 5 / 9;
console.log(`伦敦今天 ${londonF}°F，相当于 ${londonC}°C。`);
const wrongC = londonF - 32 * 5 / 9;
console.log(`不加括号算出来是 ${wrongC}`);运行结果：
伦敦今天 59°F，相当于 15°C。
不加括号算出来是 41.22222222222222不加括号时先算乘除：32 × 5 ÷ 9 约等于 17.78，再用 59 去减，结果完全错了。
练习 6：计算年龄
新建 day13-age.js。用你的出生年份和今年的年份算出年龄，再算出“距离 30 岁还有几年”，输出两句话。
提示：需要三个 const：出生年份、今年、年龄。“还有几年”就是 30 减去年龄。
learn/js/day13-age.js
const birthYear = 1998; // 换成你自己的出生年份
const currentYear = 2026;
const age = currentYear - birthYear;
console.log(`今年 ${age} 岁。`);
console.log(`距离 30 岁还有 ${30 - age} 年。`);运行结果：
今年 28 岁。
距离 30 岁还有 2 年。这只按年份粗算，没有考虑今年生日过了没有。DAY 15 学了日期之后，你可以回来改得更准确。
练习 7：拼一句三个世界的介绍
新建 day13-worlds.js。用 6 个 const 分别存三个世界的名字和给人的感觉，然后用一个模板字符串拼出这句话：我是东哥。绅士给你安全感，街头给你心动，泰风给你被保护感。
提示：变量名可以叫 gentleman 和 gentlemanFeeling，其余两个世界同理。
learn/js/day13-worlds.js
const gentleman = "绅士";
const gentlemanFeeling = "安全感";
const street = "街头";
const streetFeeling = "心动";
const thai = "泰风";
const thaiFeeling = "被保护感";
const line = `我是东哥。${gentleman}给你${gentlemanFeeling}，${street}给你${streetFeeling}，${thai}给你${thaiFeeling}。`;
console.log(line);运行结果：
我是东哥。绅士给你安全感，街头给你心动，泰风给你被保护感。练习 8：把秒数换成“几分几秒”
新建 day13-duration.js。一条视频长 95 秒，输出“这条视频时长 1 分 35 秒”。要求程序自己算，不能直接写 1 和 35。
提示：分钟数是 95 除以 60 之后“向下取整”，JavaScript 里向下取整用 Math.floor()，比如 Math.floor(1.9) 得到 1。剩下的秒数用上午学的 %。
learn/js/day13-duration.js
const totalSeconds = 95;
const minutes = Math.floor(totalSeconds / 60);
const seconds = totalSeconds % 60;
console.log(`这条视频时长 ${minutes} 分 ${seconds} 秒`);运行结果：
这条视频时长 1 分 35 秒把 95 改成 200 再运行，应该得到 3 分 20 秒。
练习 9：字符串里的数字
新建 day13-followers.js。假设从网页输入框拿到了两个值：现有粉丝 "1200"，今天新增 "35"（注意都带引号，是字符串）。先直接相加看看结果，再改成正确的写法，得到 1235。
提示：用 Number() 分别转换两个值再相加。
learn/js/day13-followers.js
const current = "1200";
const today = "35";
console.log(current + today);
const total = Number(current) + Number(today);
console.log(total);
console.log(typeof total);运行结果：
120035
1235
number直接相加时两边都是字符串，+ 做的是拼接，得到 "120035"。
练习 10：一年能更新多少条
新建 day13-plan.js。按官网的每周节目单，你每周更新 6 条（周一到周五，加上周日）。一年按 52 周算，一年一共更新多少条？如果每条剪辑要 2.5 小时，一年花在剪辑上多少小时？
提示：三个 const 存已知条件，两个 const 存计算结果。
learn/js/day13-plan.js
const videosPerWeek = 6;
const weeksPerYear = 52;
const hoursPerVideo = 2.5;
const videosPerYear = videosPerWeek * weeksPerYear;
const editingHours = videosPerYear * hoursPerVideo;
console.log(`一年更新 ${videosPerYear} 条视频。`);
console.log(`一年剪辑 ${editingHours} 小时。`);运行结果：
一年更新 312 条视频。
一年剪辑 780 小时。提交到 Git
今天的练习都在 learn 仓库里，提交并推到 GitHub：
cd ~/code/learn
git add js
git commit -m "DAY 13：变量与数据类型练习"
git pushnode 文件名.js 运行，都和参考答案的结果一致。let 或 const 声明过这个名字。刷新页面（清空之前的所有变量）再粘贴。写在 .js 文件里时，检查同一个文件里是不是写了两次 const 同一个名字。pwd 看你在哪个文件夹，用 ls 看文件名拼写，确认先 cd ~/code/learn/js 再运行。另外检查 VS Code 里文件是否已保存，标签页上有白色圆点就是没保存。` 包起来的字符串才认 ${ }。birthYear，用的时候写成了 birthyear。let 和 const 有什么区别？"5" + 3 和 "5" - 3 分别得到什么，为什么？
let 声明的变量之后可以重新赋值；const 声明的变量不能重新赋值，试图重新赋值会报 TypeError。默认用 const，确定要变的值才用 let。
"5" + 3 得到字符串 "53"：+ 两边只要有一个字符串，就做拼接，3 被转成 "3" 接在后面。"5" - 3 得到数字 2：- 只能做数学运算，会把 "5" 转成数字 5 再减。
typeof null 的结果是什么？null 和 undefined 有什么区别？
结果是 "object"，这是 JavaScript 早期留下的错误，一直保留至今。
两者都表示“没有值”。undefined 是 JavaScript 自动给的，比如声明了变量但没赋值；null 是程序员主动设的，表示“我确定这里是空的”，比如粉丝没填昵称。
5 == "5" 和 5 === "5" 分别得到什么？为什么建议永远用 ===？
5 == "5" 是 true，5 === "5" 是 false。== 会先偷偷把两边转成相同类型再比较，=== 要求值和类型都相同。偷偷转换的规则很复杂，容易得出意想不到的结果，用 === 比较的结果永远和你看到的一致。
if、else if、else 让程序根据条件走不同的路，并知道条件的先后顺序为什么重要。&&、||、! 组合条件，并能说出 "" || "匿名粉丝" 这类写法的结果。switch 处理“一个值对应多种情况”，用三元运算符在两个值里二选一。for 和 while 让程序重复做事，会用 break 和 continue，知道死循环怎么停。昨天你学了 boolean，它只有 true 和 false 两个值，当时看起来没什么用。今天它要派上大用场：程序靠它来“做决定”。
生活里你每天都在做这种判断：如果现在是晚上十点，就录《晚安三岁》；否则继续剪片子。写成 JavaScript 是这样：
const hour = 22;
if (hour === 22) {
console.log("晚安三岁开录了");
}
console.log("程序继续往下走");运行结果：
晚安三岁开录了
程序继续往下走if 后面的圆括号里是“条件”，它会被算成 true 或 false。{ } 里是“代码块”：条件为 true 时才执行。把 hour 改成 21 再运行，第一行就不会出现了。“否则做什么”用 else：
const followers = 860;
if (followers >= 1000) {
console.log("粉丝过千了，录一条感谢视频");
} else {
console.log(`离一千粉还差 ${1000 - followers} 个`);
}运行结果：
离一千粉还差 140 个情况不止两种时，用 else if 串起来。比如按官网的每周节目单，判断今天更新什么：
const day = "周三";
if (day === "周一") {
console.log("绅士线：球房一小时");
} else if (day === "周二") {
console.log("街头线：带你兜风");
} else if (day === "周三") {
console.log("泰风线：泰拳早课");
} else {
console.log("今天不是三条主线的更新日");
}运行结果：
泰风线：泰拳早课JavaScript 从上往下一个个检查条件，遇到第一个为 true 的，执行它的代码块，然后跳过剩下所有的。都不满足，就执行最后的 else。else 可以不写，不写就是“都不满足时什么也不做”。
“从上往下、第一个满足就停”这条规则，意味着条件的顺序很重要。看这段有问题的代码：
const followers = 25000;
if (followers >= 1000) {
console.log("千粉");
} else if (followers >= 10000) {
console.log("万粉");
}运行结果：
千粉明明是两万五千粉，却显示“千粉”。因为 25000 >= 1000 已经是 true，第二个条件根本没机会检查。修法是把范围小、要求高的条件放在前面：先判断 >= 10000，再判断 >= 1000。
还记得昨天讲的“假值”吗？if 的条件不一定要写成比较，任何值都行，JavaScript 会把它转成 boolean。空字符串是假值，所以可以这样判断“粉丝有没有填昵称”：
const nickname = "";
if (nickname) {
console.log(`谢谢你，${nickname}`);
} else {
console.log("谢谢你，匿名的朋友");
}运行结果：
谢谢你，匿名的朋友有时一个条件不够。“周二或周四，并且是晚上十点，才录《晚安三岁》”，这句话里有“或”也有“并且”。JavaScript 用三个逻辑运算符表达它们：
&&（并且）：两边都是 true，结果才是 true。||（或者）：两边有一个是 true，结果就是 true。| 在键盘回车键上方，按住 Shift 输入。!（不是）：把 true 变成 false，把 false 变成 true。const isWeekend = true;
const isRaining = false;
console.log(isWeekend && isRaining);
console.log(isWeekend || isRaining);
console.log(!isRaining);运行结果：
false
true
true把刚才那句话写成代码：
const day = "周四";
const hour = 22;
if ((day === "周二" || day === "周四") && hour === 22) {
console.log("《晚安三岁》开始了");
}运行结果：
《晚安三岁》开始了注意里面那对括号。&& 的优先级比 || 高，就像乘法比加法先算。不加括号的话，JavaScript 会理解成“周二，或者（周四并且十点）”，周二下午三点也会满足条件。拿不准的时候就加括号，既保证正确，也方便别人读。
|| 和 && 还有一个很实用的特点：它们返回的不一定是 true 或 false，而是两边中的某一个值。|| 从左往右找，返回第一个真值，都是假值就返回最后一个；&& 返回第一个假值，都是真值就返回最后一个。
const nickname = "";
const displayName = nickname || "匿名粉丝";
console.log(displayName);
console.log("东哥" && "在线");
console.log(0 || "没有数据");运行结果：
匿名粉丝
在线
没有数据第一段是最常见的用法：“有昵称就用昵称，没有就用默认值”，一行搞定。
这个特点还带来一个叫“短路”的现象：&& 左边已经是假值时，结果注定是假，右边就根本不会被执行；|| 左边已经是真值时，右边也不会被执行。就像你问“今天下雨并且有训练吗”，一听不下雨，后半句就不用问了。现在知道有这回事就行，以后读别人的代码时会经常见到。
最后是 !。它常用在“如果不是……”的判断里，比如 if (!isLive) 读作“如果没在直播”。有时你还会看到 !!value，两个感叹号连用，等于把一个值转成对应的 true 或 false，效果和 Boolean(value) 一样。
当你要拿同一个值和好几个固定选项逐个比较时，一长串 else if 读起来有点累，这时可以用 switch：
const world = "street";
switch (world) {
case "gentleman":
console.log("绅士：安全感");
break;
case "street":
console.log("街头：心动");
break;
case "thai":
console.log("泰风：被保护感");
break;
default:
console.log("没有这个世界");
}运行结果：
街头：心动switch (world)：拿 world 的值去比较。比较用的是严格相等 ===。case "street":：如果 world === "street"，就从这里开始执行。注意 case 后面是冒号。break;：执行完就跳出整个 switch。default:：所有 case 都不匹配时执行，相当于 else。break 千万不能忘。忘了会怎样？把上面的 break 全删掉：
const world = "street";
switch (world) {
case "gentleman":
console.log("绅士：安全感");
case "street":
console.log("街头：心动");
case "thai":
console.log("泰风：被保护感");
default:
console.log("没有这个世界");
}运行结果：
街头：心动
泰风：被保护感
没有这个世界从匹配的 case 开始，程序会一路往下执行，直到遇到 break 或 switch 结束，这叫“贯穿”。大多数时候这是 bug，但偶尔也会故意利用它，让几个 case 共用同一段代码，比如 case "周六": 和 case "周日": 连着写，下面只写一次“周末”。
如果只是根据条件在两个值里选一个，写完整的 if else 有点啰嗦。三元运算符把它压成一行：
const followers = 12000;
const label = followers >= 10000 ? "万粉博主" : "成长中";
console.log(label);运行结果：
万粉博主读法是：条件 ? 条件为真时的值 : 条件为假时的值。问号前是问题，问号后是“是”的答案，冒号后是“否”的答案。它和下面这段 if else 完全等价：
const followers = 12000;
let label;
if (followers >= 10000) {
label = "万粉博主";
} else {
label = "成长中";
}
console.log(label);运行结果：
万粉博主三元运算符适合“选一个值”这种简单情况。如果条件复杂，或者要做好几件事，老老实实写 if else，更好读。也不要把好几个三元运算符套在一起写。
泰拳训练要打 5 个回合，你不会写 5 遍一样的代码，而是让程序重复。重复固定次数，用 for 循环：
for (let round = 1; round <= 5; round++) {
console.log(`第 ${round} 回合`);
}
console.log("训练结束");运行结果：
第 1 回合
第 2 回合
第 3 回合
第 4 回合
第 5 回合
训练结束for 后面的圆括号里有三部分，用分号隔开：
let round = 1：起点。建一个计数用的变量，只在开始时执行一次。round <= 5：条件。每一轮开始前检查，true 就执行花括号里的代码，false 就结束循环。round++：每轮结束后做的事，这里是计数加 1。执行顺序是：起点，检查条件，执行代码块，加 1，检查条件，执行代码块，加 1……直到条件为 false。round 变成 6 时，6 <= 5 是 false，循环结束，程序接着执行“训练结束”那一行。
初学循环时，最好的办法是像下面这样，拿纸笔把每一轮“追踪”一遍：
| 第几轮 | round 的值 | round <= 5 ? | 做了什么 |
|---|---|---|---|
| 1 | 1 | true | 输出“第 1 回合”，round 变成 2 |
| 2 | 2 | true | 输出“第 2 回合”，round 变成 3 |
| 3 | 3 | true | 输出“第 3 回合”，round 变成 4 |
| 4 | 4 | true | 输出“第 4 回合”，round 变成 5 |
| 5 | 5 | true | 输出“第 5 回合”，round 变成 6 |
| 结束 | 6 | false | 跳出循环，输出“训练结束” |
看起来很笨，但程序员遇到看不懂的循环，真的会这样一轮一轮地推。推几次，你脑子里就有了循环的画面。
循环最常见的用法之一是“累加”：在循环外面准备一个变量，每一轮往里加一点。比如算 1 加到 100：
let total = 0;
for (let i = 1; i <= 100; i++) {
total += i;
}
console.log(total);运行结果：
5050i 是计数变量最常用的名字，是 index（序号）的缩写。total 必须用 let 声明在循环外面，如果写在循环里面，每一轮都会被重新设成 0。
循环里还可以用两个关键字控制流程：continue 跳过这一轮剩下的代码，直接进入下一轮；break 立刻结束整个循环。用一周七天举例，1 到 7 代表周一到周日，周六是拍摄日不更新：
for (let day = 1; day <= 7; day++) {
if (day === 6) {
continue;
}
console.log(`第 ${day} 天：更新`);
}运行结果：
第 1 天：更新
第 2 天：更新
第 3 天：更新
第 4 天：更新
第 5 天：更新
第 7 天：更新再用 BMX 练一个新动作举例，最多试 10 次，成功了就收工：
for (let attempt = 1; attempt <= 10; attempt++) {
console.log(`第 ${attempt} 次尝试`);
if (attempt === 3) {
console.log("成功落地，收工");
break;
}
}运行结果：
第 1 次尝试
第 2 次尝试
第 3 次尝试
成功落地，收工有些事你事先不知道要重复几次，只知道什么时候停。比如：现在 1000 个粉丝，假设每个月涨 20%，几个月能过万？这时用 while：
let followers = 1000;
let months = 0;
while (followers < 10000) {
followers = followers * 1.2;
months++;
}
console.log(`${months} 个月后粉丝过万`);
console.log(Math.round(followers));运行结果：
13 个月后粉丝过万
10699while (条件)：只要条件是 true，就一直重复执行花括号里的代码。每一轮开始前检查一次。Math.round() 是四舍五入，昨天学的 Math.floor() 是向下取整，它们都是 JavaScript 自带的数学工具。如果忘了写 followers = followers * 1.2;，followers 永远是 1000，条件永远是 true，循环永远不会结束，这叫死循环。程序会一直占着电脑不放：在终端里运行时按 Ctrl + C 强制停止；在浏览器里，页面会卡死，直接关掉这个标签页。
怎么选？知道次数（5 个回合、1 到 100）用 for；只知道停止条件（直到过万、直到猜对）用 while。
循环的结果和你想的不一样时，有一个万能的调试办法：在循环里加一行 console.log，把每一轮的关键变量都打印出来，相当于让程序自己帮你做上面那张追踪表：
let followers = 1000;
let months = 0;
while (followers < 10000) {
followers = followers * 1.2;
months++;
console.log(`第 ${months} 个月：${Math.round(followers)}`);
}运行结果：
第 1 个月：1200
第 2 个月：1440
第 3 个月：1728
第 4 个月：2074
第 5 个月：2488
第 6 个月：2986
第 7 个月：3583
第 8 个月：4300
第 9 个月：5160
第 10 个月：6192
第 11 个月：7430
第 12 个月：8916
第 13 个月：10699第 12 个月还差一点，第 13 个月过万，和前面的结果对上了。确认没问题后，把调试用的那行删掉。以后写程序遇到“不知道哪里错了”，第一反应就应该是：把中间结果打印出来看看。
循环里面可以再放一个循环。外层每走一步，内层要完整地走一遍：
for (let week = 1; week <= 2; week++) {
for (let day = 1; day <= 3; day++) {
console.log(`第 ${week} 周，第 ${day} 天`);
}
}运行结果：
第 1 周，第 1 天
第 1 周，第 2 天
第 1 周，第 3 天
第 2 周，第 1 天
第 2 周，第 2 天
第 2 周，第 3 天数一数：外层 2 轮，每一轮内层 3 轮，一共输出 2 × 3 = 6 行。注意内层的 let day = 1 在外层每走一步时都会重新执行一次，所以每周都从第 1 天重新数起。外层像时钟的时针，内层像分针：时针走一格，分针要转完一整圈。
下午要打印九九乘法表，每一行有好几个算式。console.log 每次都会换行，所以要先用一个字符串把一行“攒”起来，攒够了再一次性输出：
let line = "";
for (let i = 1; i <= 5; i++) {
line += "★";
}
console.log(line);运行结果：
★★★★★最后说说下午的重头戏 FizzBuzz。这是一道经典的编程入门题，很多公司面试时还会考。题目是：打印 1 到 100，但遇到 3 的倍数打印 Fizz，遇到 5 的倍数打印 Buzz，既是 3 又是 5 的倍数打印 FizzBuzz，其他情况打印数字本身。
先别急着写，把题目拆成你已经会的东西：
i % 3 === 0。想清楚这四点，代码就只剩十行左右。下午先自己写，写不出来再看提示。明天 DAY 15 学函数，你会把今天写的这些程序整理成可以反复调用的“工具”。
准备今天的练习文件
cd ~/code/learn/js
touch day14-level.js day14-schedule.js day14-live.js day14-fizzbuzz.js day14-table.js day14-bmx.js
code .touch 后面可以跟好几个文件名，一次全部建好。每写完一个就在终端用 node 文件名.js 运行。
练习 1：粉丝等级
在 day14-level.js 里，用一个变量存粉丝数，按下面的规则输出等级：一万及以上输出“万粉”，一千及以上输出“千粉”，其余输出“起步中”。分别把粉丝数改成 25000、3200、80 各运行一次。
提示：用 if、else if、else，注意条件的顺序。
learn/js/day14-level.js
const followers = 25000;
if (followers >= 10000) {
console.log("万粉");
} else if (followers >= 1000) {
console.log("千粉");
} else {
console.log("起步中");
}运行结果：
万粉改成 3200 应该输出“千粉”，改成 80 应该输出“起步中”。
练习 2：用 switch 写每周节目单
在 day14-schedule.js 里，用数字 0 到 6 表示星期几，0 表示周日，1 表示周一，依此类推（明天你会知道 JavaScript 的日期就是这样编号的）。用 switch 按官网节目单输出当天的节目：周一绅士线、周二街头线、周三泰风线、周四三岁时刻、周五三岁换装、周六拍摄日不更新、周日今天带你去。不是 0 到 6 的数字输出“没有这一天”。
提示：每个 case 后面别忘了 break。
learn/js/day14-schedule.js
const dayNumber = 4;
switch (dayNumber) {
case 1:
console.log("周一：绅士线");
break;
case 2:
console.log("周二：街头线");
break;
case 3:
console.log("周三：泰风线");
break;
case 4:
console.log("周四：三岁时刻");
break;
case 5:
console.log("周五：三岁换装");
break;
case 6:
console.log("周六：拍摄日，不更新");
break;
case 0:
console.log("周日：今天带你去");
break;
default:
console.log("没有这一天");
}运行结果：
周四：三岁时刻注意 case 后面写的是数字 4，不是字符串 "4"。switch 用严格相等比较，如果 dayNumber 是 4 而 case 写成 "4"，永远匹配不上。
练习 3：《晚安三岁》开播了吗
在 day14-live.js 里，用两个变量存“星期几”（字符串，如 "周二"）和“几点”（数字，如 22）。《晚安三岁》在周二和周四的 22 点播出。用一个三元运算符得到提示文字：满足就是“正在播出”，否则是“还没到时间”，然后输出。
提示：条件部分要用到 || 和 &&，别忘了括号。
learn/js/day14-live.js
const day = "周二";
const hour = 22;
const status = (day === "周二" || day === "周四") && hour === 22 ? "正在播出" : "还没到时间";
console.log(status);运行结果：
正在播出把 day 改成 "周三"，或者把 hour 改成 21，都应该输出“还没到时间”。
练习 4：FizzBuzz
在 day14-fizzbuzz.js 里，打印 1 到 100。3 的倍数打印 Fizz，5 的倍数打印 Buzz，同时是 3 和 5 的倍数打印 FizzBuzz，其他打印数字本身。先按上午第 7 节的四步思路自己写，至少独立尝试 20 分钟再看提示。
提示一：循环变量从 1 开始，条件是 <= 100。提示二：“同时是 3 和 5 的倍数”可以写成 i % 3 === 0 && i % 5 === 0，也可以写成 i % 15 === 0。提示三：这个条件必须放在最前面。
learn/js/day14-fizzbuzz.js
for (let i = 1; i <= 100; i++) {
if (i % 15 === 0) {
console.log("FizzBuzz");
} else if (i % 3 === 0) {
console.log("Fizz");
} else if (i % 5 === 0) {
console.log("Buzz");
} else {
console.log(i);
}
}输出一共 100 行，前 15 行是：
1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz如果你的第 15 行是 Fizz，说明把 i % 3 === 0 放在了最前面，15 在第一个条件就被截住了。检查完后，删掉文件，明天不看答案再写一遍。
练习 5：猜数字小游戏（在浏览器里玩）
这个游戏要和人互动，所以在浏览器里运行。新建两个文件：
touch day14-guess.html day14-guess.jslearn/js/day14-guess.html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>猜数字</title>
</head>
<body>
<h1>猜数字</h1>
<p>刷新页面就能再玩一局。</p>
<script src="day14-guess.js"></script>
</body>
</html>最后那行 <script src="..."> 的作用是让网页加载并运行 day14-guess.js，和 <link> 引入 CSS 类似。
在 day14-guess.js 里写游戏：程序随机想一个 1 到 100 的整数，一次次弹窗让玩家猜，猜大了提示“大了”，猜小了提示“小了”，猜对了显示一共猜了几次，然后结束。玩家点“取消”就告诉他答案并结束。
你需要四个新工具：
Math.random()：得到一个 0 到 1 之间的随机小数（可能是 0，但不会是 1）。乘以 100 再用 Math.floor() 向下取整，得到 0 到 99，再加 1 就是 1 到 100。prompt("提示文字")：弹出输入框，返回玩家输入的字符串；玩家点取消时返回 null。alert("文字")：弹出一个只有“确定”的提示框。Number.isNaN(值)：判断一个值是不是 NaN，是就返回 true。用来发现玩家输入的不是数字。提示：不知道要猜几次，所以用 while；用一个 boolean 变量记录“猜对了没有”；用 break 处理点取消的情况。写完用 Chrome 打开 day14-guess.html（在终端运行 open -a "Google Chrome" day14-guess.html）。
learn/js/day14-guess.js
const secret = Math.floor(Math.random() * 100) + 1;
let tries = 0;
let guessed = false;
while (!guessed) {
const input = prompt("猜一个 1 到 100 的整数：");
if (input === null) {
alert(`不玩了？答案是 ${secret}`);
break;
}
const guess = Number(input);
tries++;
if (input.trim() === "" || Number.isNaN(guess)) {
alert("请输入一个数字");
} else if (guess > secret) {
alert("大了");
} else if (guess < secret) {
alert("小了");
} else {
alert(`猜对了！答案就是 ${secret}，你一共猜了 ${tries} 次`);
guessed = true;
}
}逐行说明几个关键点：while (!guessed) 读作“只要还没猜对，就继续”。input === null 必须最先判断，因为点了取消之后 input 是 null，后面再对它做任何操作都会出错。input.trim() 会去掉字符串两头的空格，如果玩家什么都没填就点确定，得到空字符串，而 Number("") 是 0，不单独判断的话会被当成猜了 0。
小技巧：用二分法猜，先猜 50，大了就猜 25，小了就猜 75，每次把范围砍一半，最多 7 次一定能猜中。
练习 6：九九乘法表
在 day14-table.js 里，用两层 for 循环打印九九乘法表。第 1 行是 1×1=1，第 2 行是 1×2=2 2×2=4，第 9 行有 9 个算式。同一行的算式之间用两个空格隔开。
提示：外层循环控制第几行（i 从 1 到 9），内层循环控制这一行的第几个算式（j 从 1 到 i）。每一行开始前准备一个空字符串，内层循环往里拼，内层结束后输出。乘号 × 可以直接复制题目里的。
learn/js/day14-table.js
for (let i = 1; i <= 9; i++) {
let line = "";
for (let j = 1; j <= i; j++) {
line += `${j}×${i}=${i * j}`;
if (j < i) {
line += " ";
}
}
console.log(line);
}运行结果：
1×1=1
1×2=2 2×2=4
1×3=3 2×3=6 3×3=9
1×4=4 2×4=8 3×4=12 4×4=16
1×5=5 2×5=10 3×5=15 4×5=20 5×5=25
1×6=6 2×6=12 3×6=18 4×6=24 5×6=30 6×6=36
1×7=7 2×7=14 3×7=21 4×7=28 5×7=35 6×7=42 7×7=49
1×8=8 2×8=16 3×8=24 4×8=32 5×8=40 6×8=48 7×8=56 8×8=64
1×9=9 2×9=18 3×9=27 4×9=36 5×9=45 6×9=54 7×9=63 8×9=72 9×9=81if (j < i) 的作用是：只有不是这一行最后一个算式时才加空格，这样行尾不会多出空格。内层循环的条件是 j <= i 而不是 j <= 9，所以第几行就有几个算式，打印出来是个三角形。
练习 7：BMX 练习计划
在 day14-bmx.js 里：第 1 天练 20 分钟，之后每天比前一天多练 5 分钟。第几天的单日练习时间第一次超过 60 分钟？用 while 循环算出来，输出天数和那天的分钟数。
提示：两个 let 变量，一个记第几天，一个记当天分钟数。“超过 60”是 > 60，那么循环继续的条件是什么？
learn/js/day14-bmx.js
let day = 1;
let minutes = 20;
while (minutes <= 60) {
day++;
minutes += 5;
}
console.log(`第 ${day} 天练 ${minutes} 分钟，第一次超过 60 分钟`);运行结果：
第 10 天练 65 分钟，第一次超过 60 分钟循环继续的条件正好和目标相反：目标是“超过 60”，所以“还没超过 60”（minutes <= 60）时继续。第 9 天正好 60 分钟，没有超过，所以还要再走一轮。
练习 8：循环里做判断
在 day14-bmx.js 末尾继续写：1 到 100 里，能被 7 整除的数一共有几个？用 for 循环加 if 数出来。
提示：在循环外面准备一个计数变量 count，从 0 开始，遇到符合条件的就 count++。
let count = 0;
for (let i = 1; i <= 100; i++) {
if (i % 7 === 0) {
count++;
}
}
console.log(`1 到 100 里有 ${count} 个数能被 7 整除`);运行结果：
1 到 100 里有 14 个数能被 7 整除提交到 Git
cd ~/code/learn
git add js
git commit -m "DAY 14：条件与循环练习"
git pushgit log --oneline 的第一行是今天的提交。睡前合上所有资料，在一个新文件里把 FizzBuzz 再写一遍，这就是今晚的验收。i++ 写成了 i--。按 Ctrl + C 停止，再检查“每一轮是什么在变”。浏览器里卡死的话，直接关掉标签页。if (day = "周一") 不是比较，而是赋值，条件永远成立。比较要用 ===。break，程序一路贯穿到下面的 case。}。在 VS Code 里把光标放在一个花括号旁边，和它配对的那个会被高亮，顺着找缺在哪。坚持缩进，这类错误会少很多。<script src="day14-guess.js"> 的文件名是否和真实文件一致，再按 Cmd + Option + J 打开控制台看有没有红色报错。不看资料写出 FizzBuzz。
for (let i = 1; i <= 100; i++) {
if (i % 15 === 0) {
console.log("FizzBuzz");
} else if (i % 3 === 0) {
console.log("Fizz");
} else if (i % 5 === 0) {
console.log("Buzz");
} else {
console.log(i);
}
}评判标准：能运行，第 3 行 Fizz、第 5 行 Buzz、第 15 行 FizzBuzz、第 100 行 Buzz。关键是能说清“为什么 15 的判断要放在最前面”：if 链从上往下，遇到第一个满足的就停，15 也满足“3 的倍数”，放在后面就轮不到它。
"" || "匿名粉丝" 和 "东哥" && "在线" 分别得到什么？为什么？
第一个得到 "匿名粉丝"：|| 返回第一个真值，空字符串是假值，所以返回右边。第二个得到 "在线"：&& 返回第一个假值，两边都是真值时返回最后一个，也就是右边的 "在线"。
下面这段代码运行后会怎样？怎么让它停下来，又该怎么改？
let followers = 1000;
while (followers < 10000) {
console.log(followers);
}它是死循环：循环体里没有任何代码改变 followers，它永远是 1000，条件永远为 true，终端会不停地打印 1000。在终端里按 Ctrl + C 强制停止。修改方法是在循环体里让 followers 变大，比如加一行 followers = followers * 1.2;，让条件最终变成 false。
return 和 console.log 的区别，并举出“函数忘了 return”导致出错的例子。return。formatDate 函数，把一个日期变成“10月1日 周四”这样的文字。前两天你写了温度换算、粉丝等级、FizzBuzz。想象一下：你要把曼谷、伦敦、首尔十个城市的温度都换算一遍，最直接的办法是把公式复制十遍。可万一公式写错了一个符号，你就得改十个地方，漏改一处就是一个 bug。
函数就是解决这个问题的。它像一张菜谱：写一次，以后想做这道菜，照着菜谱做就行，不用每次重新发明。菜谱上写着“需要什么材料”（参数），照着做完会“端出一盘菜”（返回值）。
函数带来三个好处：
formatDate(today) 这几个字母，比五六行取月份、取星期的代码好懂得多。读代码的人看名字就知道它在做什么，不用关心里面怎么实现。其实你已经用过好几个函数了：console.log()、Number()、Math.floor()、prompt()。它们都是 JavaScript 自带的，名字后面跟一对圆括号，括号里放东西，它帮你做一件事。今天你要学会写自己的函数。
function sayGoodnight() {
console.log("今天就到这里。");
console.log("晚安，三岁。");
}
sayGoodnight();
sayGoodnight();运行结果：
今天就到这里。
晚安，三岁。
今天就到这里。
晚安，三岁。function：关键字，表示“我要写一个函数”。sayGoodnight：函数名，命名规则和变量一样，习惯用动词开头，说明它“做什么”，比如 say、show、format、calc。()：放参数的地方，这个函数不需要参数，所以是空的。{ }：函数体，也就是菜谱的步骤。sayGoodnight(); 是“调用”，也就是照着菜谱做一次。写了两次，就执行了两次。关键的一点：声明函数时，里面的代码不会执行，只是把菜谱写好放着。只有调用时才会执行。调用一定要带圆括号，只写 sayGoodnight 不带括号，函数不会运行。
一个只会说固定台词的函数用处有限。让函数接收“材料”，它就能处理不同的情况：
function introWorld(world, feeling) {
console.log(`${world}世界，给你${feeling}。`);
}
introWorld("绅士", "安全感");
introWorld("街头", "心动");
introWorld("泰风");运行结果：
绅士世界，给你安全感。
街头世界，给你心动。
泰风世界，给你undefined。world 和 feeling 叫参数。它们像菜谱上写的“主料”“配料”，只是占位的名字，函数内部可以像变量一样使用它们。"绅士"、"安全感" 是这一次实际传进去的值。第一次调用时，world 就是 "绅士"，feeling 就是 "安全感"。undefined。可以给参数设一个默认值，没传的时候就用它：
function greet(nickname = "朋友") {
console.log(`你好，${nickname}`);
}
greet("小鹿");
greet();运行结果：
你好，小鹿
你好，朋友这是今天最重要的一节。前面的函数都是自己 console.log 一下就完了，结果显示在屏幕上，但程序拿不到它，没法接着用。好比榨汁机把果汁洒在了桌上，而不是倒进杯子里。
return 就是“把结果倒进杯子里交给你”：
function toFahrenheit(celsius) {
return celsius * 9 / 5 + 32;
}
const bangkok = toFahrenheit(33);
console.log(bangkok);
console.log(toFahrenheit(0) + 1);
console.log(`首尔 15°C，相当于 ${toFahrenheit(15)}°F`);运行结果：
91.4
33
首尔 15°C，相当于 59°F调用 toFahrenheit(33) 时，程序一步步做了这些事：
celsius = 33。理解返回值的窍门是：把函数调用想象成被它的返回值替换掉。toFahrenheit(33) 算完之后，整个这一块就变成了 91.4，所以 const bangkok = toFahrenheit(33); 等于 const bangkok = 91.4;。同理，toFahrenheit(0) + 1 变成 32 + 1。返回值可以存进变量、参与运算、放进模板字符串，想怎么用就怎么用。
如果忘了写 return 会怎样？
function toFahrenheitBroken(celsius) {
celsius * 9 / 5 + 32;
}
const result = toFahrenheitBroken(33);
console.log(result);
console.log(result + 1);运行结果：
undefined
NaN函数里的算式确实算了，但算完就扔掉了。没有 return 的函数，返回值是 undefined。更麻烦的是，程序不会报错，undefined 加 1 变成 NaN，错误会悄悄地一路传下去，等你发现时已经很难找到源头。这就是今晚验收题要你举的例子。
再看一个很多新手都会犯的混淆：用 console.log 代替 return。
function toFahrenheitLog(celsius) {
console.log(celsius * 9 / 5 + 32);
}
const value = toFahrenheitLog(33);
console.log(value);运行结果：
91.4
undefined屏幕上确实出现了 91.4，看起来函数“成功了”，但 value 里什么都没有。console.log 是“给人看”，return 是“交给程序用”，两者完全是两回事。现在你也能明白 DAY 13 控制台里那行灰色的 undefined 了：console.log 本身就是一个没有返回值的函数，控制台把它的返回值 undefined 也显示了出来。
return 还有一个作用：执行到它，函数立刻结束，后面的代码都不再执行。利用这一点，可以把昨天的粉丝等级写得很干净：
function levelOf(followers) {
if (followers >= 10000) {
return "万粉";
}
if (followers >= 1000) {
return "千粉";
}
return "起步中";
}
console.log(levelOf(25000));
console.log(levelOf(3200));
console.log(levelOf(80));运行结果：
万粉
千粉
起步中25000 在第一个 if 就 return 了，后面两段根本没机会执行，所以这里不需要写 else。一次写好，传不同的粉丝数就能反复用，这就是函数的威力。
除了用 function 名字() {} 声明，函数还可以像一个值一样，存进变量里。下面三种写法，效果完全一样：
const toCelsius = function (fahrenheit) {
return (fahrenheit - 32) * 5 / 9;
};
const toCelsiusArrow = (fahrenheit) => {
return (fahrenheit - 32) * 5 / 9;
};
const toCelsiusShort = (fahrenheit) => (fahrenheit - 32) * 5 / 9;
console.log(toCelsius(59));
console.log(toCelsiusArrow(59));
console.log(toCelsiusShort(59));运行结果：
15
15
15function 这个词，在参数和花括号之间加一个箭头 =>。箭头函数有两条规则要记牢：
() => "晚安"。只有一个参数时括号可以省略，但为了统一，建议一直写上，你装的 Prettier 插件默认也会帮你加上。第一条规则是最常见的坑：
const double = (n) => { n * 2 };
console.log(double(5));运行结果：
undefined写了花括号，却没写 return，于是返回 undefined。改法有两种：去掉花括号写成 (n) => n * 2，或者保留花括号写成 (n) => { return n * 2; }。
该用哪种？两种你都要能看懂，因为后面的 React 代码里到处是箭头函数。本课表的习惯是：独立的、有名字的工具函数用 function 声明，比如今天的 formatDate；明天要学的“交给别的函数使用的小函数”用箭头函数。
function 声明的函数，可以在声明它的代码之前调用，JavaScript 会先把所有函数声明找出来。用 const 存的箭头函数不行，提前调用会报错 ReferenceError: Cannot access 'toCelsiusShort' before initialization。养成“先写函数，再调用”的习惯，就不会碰到这个问题。打个比方：你家里的东西只有家里人能用，小区的健身房所有住户都能用。函数就像一套房子，在函数里面声明的变量是“家里的东西”，只在这个函数里面能用；在所有函数外面声明的变量是“小区公共设施”，哪里都能用。
const brand = "三岁的东哥";
function showSlogan() {
const slogan = "在你面前三岁";
console.log(`${brand}：${slogan}`);
}
showSlogan();
console.log(brand);
console.log(slogan);前两行正常输出，第三个 console.log 会报错（Chrome 里报错以 Uncaught 开头，Node 还会多显示几行出错的位置）：
三岁的东哥：在你面前三岁
三岁的东哥
ReferenceError: slogan is not defined函数里面可以用外面的 brand，外面却看不到函数里面的 slogan。变量能被看到的范围，就叫作用域。
不只是函数，任何一对花括号都会形成自己的作用域，比如 if 和 for 的代码块。用 let 和 const 在花括号里声明的变量，出了花括号就不存在了。昨天 for 循环里的 let i 也一样，循环结束后在外面用 i 会报错。这就是 DAY 13 说的 var 的怪脾气之一：var 声明的变量不认 if 和 for 的花括号，会“漏”到外面去，容易造成意外。
如果函数里面声明了一个和外面同名的变量，函数里用的是自己的那个，外面的不受影响：
const world = "绅士";
function showWorld() {
const world = "街头";
console.log(world);
}
showWorld();
console.log(world);运行结果：
街头
绅士作用域看起来像是限制，其实是保护。每个函数有自己的“房间”，你在 A 函数里起名叫 result，不用担心和 B 函数里的 result 打架。好的函数就像一个封闭的盒子：材料从参数进来，结果从 return 出去，不偷偷读写外面的变量。这样的函数最容易理解，也最容易检查对不对。DAY 51 你会给这样的函数写自动测试。
据此，写函数时养成三条习惯：
下午要写一个 formatDate 函数，需要先认识 JavaScript 自带的日期工具 Date。
const day = new Date(2026, 9, 1);
console.log(day.getFullYear());
console.log(day.getMonth());
console.log(day.getDate());
console.log(day.getDay());运行结果：
2026
9
1
4new Date(2026, 9, 1)：创建一个日期，三个数字依次是年、月、日。注意月份从 0 开始数：0 是一月，9 是十月，11 是十二月。所以这一行表示的是 2026 年 10 月 1 日，不是 9 月 1 日。这是 JavaScript 里最出名的坑之一。new Date()：括号里什么都不写，得到的是“此时此刻”。getFullYear() 取出年份。getMonth() 取出月份，同样从 0 开始，所以显示给人看时要加 1。getDate() 取出几号。名字容易和下面那个搞混，记住 Date 是“日期里的第几天”。getDay() 取出星期几：0 是周日，1 是周一，6 是周六。昨天 switch 练习里的编号就是照这个来的。所以 4 表示 2026 年 10 月 1 日是周四。day.getMonth() 这种写法，是在日期上调用它自带的函数，这类“属于某个东西的函数”叫方法，DAY 17 学对象时会细讲。下午你要把这几块拼起来：月份加 1、拿到几号、把 0 到 6 的数字变成“周日”到“周六”，最后拼成“10月1日 周四”。明天 DAY 16 学数组，你会发现“把数字变成周几”有更简单的写法。
准备今天的练习文件
cd ~/code/learn/js
touch day15-temperature.js day15-age.js day15-fizzbuzz.js day15-table.js day15-guess.js day15-date.js day15-scope.js
code .今天的主题是“把前两天的练习改写成函数”。每道题都是：先写函数，再在文件末尾调用它几次，用 node 文件名.js 检查结果。
练习 1：温度换算函数
在 day15-temperature.js 里写两个函数：toFahrenheit(celsius) 返回华氏度，toCelsius(fahrenheit) 返回摄氏度。然后用它们输出两句话：曼谷 33°C 相当于多少 °F，伦敦 59°F 相当于多少 °C。
提示：函数里只负责计算和 return，不要在函数里 console.log，输出放在函数外面做。
learn/js/day15-temperature.js
function toFahrenheit(celsius) {
return celsius * 9 / 5 + 32;
}
function toCelsius(fahrenheit) {
return (fahrenheit - 32) * 5 / 9;
}
console.log(`曼谷 33°C，相当于 ${toFahrenheit(33)}°F`);
console.log(`伦敦 59°F，相当于 ${toCelsius(59)}°C`);运行结果：
曼谷 33°C，相当于 91.4°F
伦敦 59°F，相当于 15°C对比 DAY 13 的写法：公式现在只写了一次，以后要换算多少个城市，都只是多调用一次。
练习 2：年龄函数和默认参数
在 day15-age.js 里写 calcAge(birthYear, currentYear) 返回年龄；再写 yearsUntil(age, target) 返回“离目标年龄还有几年”，target 默认是 30。用你的出生年份调用它们，输出两句话。
提示：默认参数写在括号里：target = 30。第二个函数可以直接用第一个函数的返回值作为参数。
learn/js/day15-age.js
function calcAge(birthYear, currentYear) {
return currentYear - birthYear;
}
function yearsUntil(age, target = 30) {
return target - age;
}
const age = calcAge(1998, 2026); // 换成你自己的出生年份
console.log(`今年 ${age} 岁`);
console.log(`离 30 岁还有 ${yearsUntil(age)} 年`);
console.log(`离 35 岁还有 ${yearsUntil(age, 35)} 年`);运行结果：
今年 28 岁
离 30 岁还有 2 年
离 35 岁还有 7 年练习 3：FizzBuzz 函数
在 day15-fizzbuzz.js 里写 fizzBuzz(n)：它只处理一个数字，返回这个数字对应的文字（"Fizz"、"Buzz"、"FizzBuzz" 或数字本身）。然后用 for 循环调用它，打印 1 到 15 的结果。
提示：用上午第 4 节 levelOf 的写法，一个 if 一个 return，不需要 else。数字本身用 String(n) 返回，这样函数不管什么情况都返回字符串，用起来更省心。
learn/js/day15-fizzbuzz.js
function fizzBuzz(n) {
if (n % 15 === 0) {
return "FizzBuzz";
}
if (n % 3 === 0) {
return "Fizz";
}
if (n % 5 === 0) {
return "Buzz";
}
return String(n);
}
for (let i = 1; i <= 15; i++) {
console.log(fizzBuzz(i));
}运行结果：
1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz把“判断一个数”和“循环打印”分开之后，想单独检查某个数，直接写 console.log(fizzBuzz(30)) 就行，不用跑完整个循环。
练习 4：乘法表的一行
在 day15-table.js 里写 tableRow(n)：返回九九乘法表第 n 行的字符串，比如 tableRow(3) 返回 "1×3=3 2×3=6 3×3=9"。再写一个循环，用它打印完整的九九乘法表。
提示：把昨天内层循环那部分搬进函数，最后 return line;。
learn/js/day15-table.js
function tableRow(n) {
let line = "";
for (let j = 1; j <= n; j++) {
line += `${j}×${n}=${j * n}`;
if (j < n) {
line += " ";
}
}
return line;
}
console.log(tableRow(3));
console.log("----");
for (let i = 1; i <= 9; i++) {
console.log(tableRow(i));
}运行结果：
1×3=3 2×3=6 3×3=9
----
1×1=1
1×2=2 2×2=4
1×3=3 2×3=6 3×3=9
1×4=4 2×4=8 3×4=12 4×4=16
1×5=5 2×5=10 3×5=15 4×5=20 5×5=25
1×6=6 2×6=12 3×6=18 4×6=24 5×6=30 6×6=36
1×7=7 2×7=14 3×7=21 4×7=28 5×7=35 6×7=42 7×7=49
1×8=8 2×8=16 3×8=24 4×8=32 5×8=40 6×8=48 7×8=56 8×8=64
1×9=9 2×9=18 3×9=27 4×9=36 5×9=45 6×9=54 7×9=63 8×9=72 9×9=81练习 5：把猜数字的判断抽成函数
在 day15-guess.js 里写 checkGuess(guess, secret)：猜大了返回 "大了"，猜小了返回 "小了"，猜中返回 "猜对了"。先在 Node 里用几组数字测试它。
提示：这个函数不需要 prompt 和 alert，只做判断，所以能在 Node 里测试。这正是把判断逻辑单独抽出来的好处。
learn/js/day15-guess.js
function checkGuess(guess, secret) {
if (guess > secret) {
return "大了";
}
if (guess < secret) {
return "小了";
}
return "猜对了";
}
console.log(checkGuess(70, 42));
console.log(checkGuess(30, 42));
console.log(checkGuess(42, 42));运行结果：
大了
小了
猜对了选做：打开昨天的 day14-guess.js，把 checkGuess 函数复制到文件最上面，再把循环里判断大小的三个分支改成 const hint = checkGuess(guess, secret); 和 alert(hint);，猜对时把 guessed 设为 true。刷新浏览器玩一局，确认游戏照常工作。
练习 6：把数字变成星期几
在 day15-date.js 里写 weekdayName(dayNumber)：传入 0 到 6，返回 "周日" 到 "周六"。
提示：可以用 switch，每个 case 里直接 return，这样连 break 都不用写，因为 return 会直接结束函数。
learn/js/day15-date.js
function weekdayName(dayNumber) {
switch (dayNumber) {
case 0:
return "周日";
case 1:
return "周一";
case 2:
return "周二";
case 3:
return "周三";
case 4:
return "周四";
case 5:
return "周五";
case 6:
return "周六";
default:
return "未知";
}
}
console.log(weekdayName(0));
console.log(weekdayName(4));运行结果：
周日
周四练习 7：formatDate
在同一个文件里继续写 formatDate(date)：接收一个日期，返回“10月1日 周四”这样的字符串。用三个日期测试：new Date(2026, 9, 1) 应该得到“10月1日 周四”，new Date(2026, 11, 25) 应该得到“12月25日 周五”，new Date(2027, 0, 1) 应该得到“1月1日 周五”。最后再用 new Date() 输出今天。
提示：函数里分三步：用 getMonth() 取月份并加 1；用 getDate() 取几号；用 getDay() 取星期数字，交给上一题的 weekdayName。最后用模板字符串拼起来 return。注意“日”和“周”之间有一个空格。
接在 weekdayName 函数和它的测试代码下面：
learn/js/day15-date.js
function weekdayName(dayNumber) {
switch (dayNumber) {
case 0:
return "周日";
case 1:
return "周一";
case 2:
return "周二";
case 3:
return "周三";
case 4:
return "周四";
case 5:
return "周五";
case 6:
return "周六";
default:
return "未知";
}
}
function formatDate(date) {
const month = date.getMonth() + 1;
const dayOfMonth = date.getDate();
const weekday = weekdayName(date.getDay());
return `${month}月${dayOfMonth}日 ${weekday}`;
}
console.log(formatDate(new Date(2026, 9, 1)));
console.log(formatDate(new Date(2026, 11, 25)));
console.log(formatDate(new Date(2027, 0, 1)));运行结果：
10月1日 周四
12月25日 周五
1月1日 周五再加一行 console.log(formatDate(new Date()));，会输出今天的日期，每天运行结果都不一样。如果你得到的月份比实际少 1，说明忘了 + 1。
练习 8：改写成箭头函数
在 day15-temperature.js 末尾，把 toFahrenheit 和 toCelsius 各改写成一行的箭头函数，起名 toF 和 toC，再用它们换算一次，确认结果和原来一样。
提示：函数体只有一个表达式，可以省略花括号和 return。
const toF = (celsius) => celsius * 9 / 5 + 32;
const toC = (fahrenheit) => (fahrenheit - 32) * 5 / 9;
console.log(toF(33));
console.log(toC(59));运行结果：
91.4
15练习 9：作用域预测题
把下面的代码写进 day15-scope.js，先在纸上写下你预测的输出，再运行对答案。
let count = 0;
function addOne() {
count++;
}
function showLocal() {
const count = 100;
console.log(count);
}
addOne();
addOne();
showLocal();
console.log(count);运行结果：
100
2addOne 里没有声明自己的 count，所以它改的是外面那个，调用两次后变成 2。showLocal 里用 const 声明了自己的 count，它显示的是自己的 100，外面的 count 不受影响。最后一行在外面，看到的是外面的 2。像 addOne 这样偷偷修改外面变量的函数，程序大了以后很难追踪，能用参数和 return 解决的，就别这样写。
提交到 Git
cd ~/code/learn
git add js
git commit -m "DAY 15：函数练习与 formatDate"
git push函数名(...) 这一行。return，或者箭头函数写了花括号却没写 return。在函数里 return 的那一行前面加个 console.log，看看算出来的值对不对。getMonth() 从 0 开始数，显示前要加 1。反过来，创建日期时 new Date(2026, 10, 1) 是 11 月 1 日，不是 10 月。getDay() 写成了 getDate()。前者是星期几（0 到 6），后者是几号（1 到 31）。参数和返回值分别是什么？举一个“函数忘了 return”导致出错的例子。
参数是函数声明时括号里的名字，是函数接收“材料”的入口，调用时传进去的值会按位置交给它们。返回值是函数用 return 交出来的结果，调用的地方可以把它存进变量、参与运算。
例子：
function toFahrenheit(celsius) {
celsius * 9 / 5 + 32;
}
const f = toFahrenheit(33);
console.log(f + 1);函数里算了，但没有 return，返回值是 undefined，所以 f 是 undefined，f + 1 得到 NaN。程序不报错，错误悄悄传下去，这正是它危险的地方。
const double = (n) => { n * 2 }; 调用 double(5) 得到什么？为什么？怎么改？
得到 undefined。箭头函数写了花括号，就变成了普通的函数体，必须自己写 return，否则返回 undefined。改成 (n) => n * 2（去掉花括号，自动返回），或者 (n) => { return n * 2; }。
new Date(2026, 9, 1) 表示几月几日？对它调用 getDay() 得到 4，是什么意思？
表示 2026 年 10 月 1 日，因为月份从 0 开始数，9 是十月。getDay() 返回星期几，0 是周日，所以 4 是周四。
push、pop、unshift、shift、splice 增删元素，用 includes、indexOf 查找元素。forEach 遍历数组，并说出“回调函数”是什么。map 生成新数组，用 filter 筛选，用 find 找出第一个符合条件的元素。到目前为止，一个变量只装一个值。可是你有四个平台，难道要写四个变量 platform1、platform2……？将来有二十套穿搭，就要写二十个变量，想“把每一套都显示出来”还得写二十行。
数组就是用来装“一组同类东西”的。你可以把它想象成衣柜里的一根挂杆，上面的衣架按顺序编了号。有一点和日常习惯不同：编号从 0 开始。这个编号叫“下标”（也叫索引，index）。
const platforms = ["小红书", "TikTok", "Facebook", "Instagram"];
console.log(platforms);
console.log(platforms.length);
console.log(platforms[0]);
console.log(platforms[3]);
console.log(platforms[platforms.length - 1]);
console.log(platforms[4]);运行结果：
[ '小红书', 'TikTok', 'Facebook', 'Instagram' ]
4
小红书
Instagram
Instagram
undefined[ ] 创建数组，元素之间用逗号隔开。元素可以是任何类型，但通常一个数组里放同一类东西。.length 是元素的个数，这里是 4。platforms[0] 取第一个元素。方括号里写下标，第一个是 0，第四个是 3。platforms[platforms.length - 1]。这样不管数组有多长都能取对。为什么从 0 开始？可以把下标理解成“离开头走了几步”：第一个元素就在开头，走了 0 步；第二个走了 1 步。这样想，platforms[0] 是第一个就不别扭了。几乎所有编程语言都这样数，刚开始容易错，写多了自然就习惯。
(4) ['小红书', 'TikTok', 'Facebook', 'Instagram']，前面的 (4) 是长度，点左边的小三角可以展开看每个下标。样子不同，内容一样。学会数组，昨天的 weekdayName 可以大大缩短。星期几的数字 0 到 6，正好可以当下标用：
const weekdays = ["周日", "周一", "周二", "周三", "周四", "周五", "周六"];
function weekdayName(dayNumber) {
return weekdays[dayNumber];
}
console.log(weekdayName(4));
console.log(weekdayName(0));运行结果：
周四
周日二十多行的 switch 变成了一行。“用一个数字去数组里查对应的值”，是非常常见的写法。
用下标可以直接改掉某个位置的值，还有四个方法专门在两头增删元素。“方法”就是跟在数组后面、用点号调用的函数，你昨天在日期上用过的 getMonth() 也是方法。
const worlds = ["绅士", "街头"];
worlds.push("泰风");
console.log(worlds);
worlds[0] = "绅士线";
console.log(worlds);
const last = worlds.pop();
console.log(last);
console.log(worlds);
worlds.unshift("三岁时刻");
console.log(worlds);
worlds.shift();
console.log(worlds);运行结果：
[ '绅士', '街头', '泰风' ]
[ '绅士线', '街头', '泰风' ]
泰风
[ '绅士线', '街头' ]
[ '三岁时刻', '绅士线', '街头' ]
[ '绅士线', '街头' ]| 方法 | 做什么 | 好记的说法 |
|---|---|---|
push(值) | 在末尾加一个 | 往挂杆最右边挂一件 |
pop() | 删掉末尾那个，并返回它 | 取下最右边那件 |
unshift(值) | 在开头加一个 | 往最左边挂一件，其他的往右挪 |
shift() | 删掉开头那个，并返回它 | 取下最左边那件 |
你可能注意到了：worlds 是用 const 声明的，为什么还能改里面的内容？因为 const 管的是“标签不能贴到别的数组上”，不管“数组里面放什么”。worlds.push(...) 没问题，worlds = ["别的"] 才会报错。
想在中间删除或插入，用 splice(从哪个下标开始, 删几个, 要插入的值...)：
const schedule = ["绅士线", "街头线", "泰风线", "三岁时刻", "三岁换装"];
schedule.splice(1, 1);
console.log(schedule);
schedule.splice(1, 0, "街头线（重播）");
console.log(schedule);运行结果：
[ '绅士线', '泰风线', '三岁时刻', '三岁换装' ]
[ '绅士线', '街头线（重播）', '泰风线', '三岁时刻', '三岁换装' ]第一次从下标 1 开始删 1 个，删掉了“街头线”。第二次从下标 1 开始删 0 个，也就是不删，只在这个位置插入一个新值。
想知道数组里有没有某个值，用 includes；想知道它在第几个，用 indexOf：
const platforms = ["小红书", "TikTok", "Facebook", "Instagram"];
console.log(platforms.includes("TikTok"));
console.log(platforms.includes("YouTube"));
console.log(platforms.indexOf("Facebook"));
console.log(platforms.indexOf("YouTube"));运行结果：
true
false
2
-1indexOf 找不到时返回 -1，因为 -1 不可能是一个真实的下标。
这里有个区别要留心：push、pop、unshift、shift、splice 会直接修改原来的数组；而下面要学的 map、filter 不动原数组，而是交给你一个新数组。后面学 React 时，“不修改原数据、生成新数据”会变得非常重要，现在先记住哪些方法会改原数组。
数组最常做的事，就是“对每个元素做同一件事”，这叫遍历。有三种写法。第一种是你昨天就会的 for 循环，用下标一个个取：
const platforms = ["小红书", "TikTok", "Facebook", "Instagram"];
for (let i = 0; i < platforms.length; i++) {
console.log(`${i + 1}. ${platforms[i]}`);
}运行结果：
1. 小红书
2. TikTok
3. Facebook
4. Instagram注意循环从 i = 0 开始，条件是 i < platforms.length（小于，不是小于等于），这样 i 正好走遍 0、1、2、3。显示给人看时加 1，从 1 开始编号。
第二种是 for...of，不需要下标时最简洁，读作“对于数组里的每一个 platform”：
const platforms = ["小红书", "TikTok", "Facebook", "Instagram"];
for (const platform of platforms) {
console.log(platform);
}运行结果：
小红书
TikTok
Facebook
Instagram第三种是数组自带的方法 forEach，它是今天后面几个方法的基础：
const platforms = ["小红书", "TikTok", "Facebook", "Instagram"];
platforms.forEach((platform, index) => {
console.log(`${index + 1}. ${platform}`);
});运行结果：
1. 小红书
2. TikTok
3. Facebook
4. Instagram这里第一次出现了一个重要的概念：把一个函数当作参数，交给另一个函数。括号里的 (platform, index) => { ... } 是一个箭头函数，你没有自己调用它，而是把它交给了 forEach。forEach 会替你调用它，每个元素调用一次，每次把“当前元素”和“它的下标”作为参数传进来。这种交给别人去调用的函数，叫回调函数。
参数名是你自己起的，习惯上用数组名的单数：platforms 里的每一个叫 platform，looks 里的每一个叫 look。不需要下标时，第二个参数可以不写。
三种写法怎么选？需要中途停下（break）或者要跳着走（比如只看偶数下标）时，用普通 for 循环；只是从头到尾走一遍，用 for...of 或 forEach 都可以。注意 forEach 里不能用 break，它一定会把每个元素都走完。本课表后面会大量使用 forEach 以及下面要学的 map、filter、find，因为它们读起来更像一句话：“对每一套穿搭，做某件事”。
下午要做的 looks 数组，每一项是一套穿搭，每套有名字、属于哪个世界、主色是什么三条信息。一个字符串装不下三条信息，这就需要对象。明天 DAY 17 会专门讲对象，今天先学够用的部分：
const look = { name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" };
console.log(look.name);
console.log(look.world);运行结果：
Baggy 裤配 Vans
street花括号 { } 创建对象，里面是一对对“名字: 值”，用逗号隔开。名字叫“属性名”，取值时用点号：look.name 读作“这套穿搭的名字”。
把好几个这样的对象放进一个数组，就是“对象数组”，这是今后你最常打交道的数据形状。后面网站里的 looks、平台列表、提问箱，数据都长这样：
learn/js/day16-looks.js
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
console.log(looks.length);
console.log(looks[2].name);
console.log(looks[looks.length - 1].world);运行结果：
6
Baggy 裤配 Vans
thailooks[2].name 从左往右读：先用下标取出第三套穿搭（一个对象），再用点号取它的名字。数组最后一个元素后面多写一个逗号是允许的，这样以后加新的一行时不容易漏逗号。color 是这套衣服的主色，用的是你在 CSS 里熟悉的十六进制颜色，DAY 19 生成卡片时会用上。
接下来的三节，都用这个 looks 数组举例。每个例子都把 looks 完整写了一遍，这样你可以单独复制任何一段去运行。
为什么需要它：你有 6 套穿搭的完整信息，但页面上只想显示名字列表。你要的是“一个新数组，里面是每套穿搭的名字”。这种“一一对应地转换”就用 map：
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const names = looks.map((look) => look.name);
console.log(names);
console.log(looks.length, names.length);运行结果：
[
'马甲三件套',
'白衬衫配牛津皮鞋',
'Baggy 裤配 Vans',
'Oversize 卫衣',
'泰拳短裤训练装',
'绑手带配运动背心'
]
6 6look.name，新数组里装的就是名字。(look) => look.name 是 DAY 15 学的简写箭头函数，省略了花括号，自动返回 look.name。可以把 map 想象成一条流水线：每件衣服依次经过同一台机器，出来的是它的“名牌”。进去几件，出来几个，顺序不变。DAY 19 你会用同样的思路，把每套穿搭变成页面上的一张卡片，DAY 28 在 React 里渲染列表时，用的也是 map。可以说，map 是前端开发里用得最多的数组方法。
回调函数也能拿到第二个参数下标，比如生成带编号的标题：
const worlds = ["gentleman", "street", "thai"];
const labels = worlds.map((world, index) => `${index + 1}号世界：${world}`);
console.log(labels);运行结果：
[ '1号世界：gentleman', '2号世界：street', '3号世界：thai' ]想只看“街头”的穿搭？用 filter（过滤）。它也接收一个回调函数，这个函数要返回 true 或 false，回答“这一项要不要留下”：
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const streetLooks = looks.filter((look) => look.world === "street");
console.log(streetLooks.length);
console.log(streetLooks[0].name);
const snookerLooks = looks.filter((look) => look.world === "snooker");
console.log(snookerLooks);运行结果：
2
Baggy 裤配 Vans
[]回调 (look) => look.world === "street" 读作“对每一套 look，问一句：它的 world 是 street 吗”。=== 本身就会算出 true 或 false，所以直接返回它就行，不需要写成 if (...) { return true; } else { return false; } 那么啰嗦。filter 对每一项调用回调，返回 true 的留下，false 的去掉，留下的组成一个新数组。filter 的结果永远是数组，一个都没筛到，就是空数组 []。
如果你只想要一个，比如“找到名字里带 Vans 的那一套”，用 find：
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const vans = looks.find((look) => look.name.includes("Vans"));
console.log(vans);
const firstThai = looks.find((look) => look.world === "thai");
console.log(firstThai.name);
const missing = looks.find((look) => look.world === "snooker");
console.log(missing);运行结果：
{ name: 'Baggy 裤配 Vans', world: 'street', color: '#3a5a80' }
泰拳短裤训练装
undefinedlook.name.includes("Vans")：字符串也有 includes 方法，判断里面是否包含某段文字。missing.name，程序会报错 TypeError: Cannot read properties of undefined (reading 'name')。用 find 的结果之前，先用 if 判断一下它是不是找到了。四个方法长得很像，都接收一个回调函数、都会遍历数组，区别在于它们返回什么：
| 方法 | 回调返回什么 | 方法本身返回什么 | 什么时候用 |
|---|---|---|---|
forEach | 不在乎 | undefined | 只是对每一项“做件事”，比如打印 |
map | 新的值 | 一样长的新数组 | 把每一项变成另一个样子 |
filter | true 或 false | 筛选后的新数组，可能为空 | 要“所有符合条件的” |
find | true 或 false | 第一个符合的元素，或 undefined | 只要“一个” |
forEach 什么也不返回，这一点可以验证。下面的 toUpperCase() 是字符串的方法，作用是把英文字母变成大写，回调确实返回了大写的名字，但 forEach 不会收集它们：
const worlds = ["gentleman", "street", "thai"];
const result = worlds.forEach((world) => world.toUpperCase());
console.log(result);运行结果：
undefined这些方法还可以接着调用，叫“链式调用”。比如“街头穿搭的名字”，就是先 filter 再 map：
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const streetNames = looks
.filter((look) => look.world === "street")
.map((look) => look.name);
console.log(streetNames);运行结果：
[ 'Baggy 裤配 Vans', 'Oversize 卫衣' ]从上往下读：从 looks 出发，筛出街头的，再取出名字。每一步都产生一个新数组，交给下一步。明天 DAY 17 深入学对象，你会用同样的方法处理四个平台的数据。
建好练习文件，写入 looks 数组
cd ~/code/learn/js
touch day16-looks.js day16-weekday.js
code day16-looks.js把上午第 4 节的 looks 数组（6 套穿搭）写进 day16-looks.js 的最上面。建议亲手敲一遍，不要复制，练习对象和数组的写法。你也可以把名字和颜色换成自己衣柜里真实的衣服，但每个世界至少保留两套，world 只能是 gentleman、street、thai 三个值之一。下面的练习都接在这个数组后面写。
console.log(looks.length);，运行 node day16-looks.js 显示 6。练习 1：基本读取
输出三行：一共有几套穿搭；第一套的名字；最后一套的名字。要求最后一套用 length 计算下标，不能直接写 5。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
console.log(`一共 ${looks.length} 套穿搭`);
console.log(`第一套：${looks[0].name}`);
console.log(`最后一套：${looks[looks.length - 1].name}`);运行结果：
一共 6 套穿搭
第一套：马甲三件套
最后一套：绑手带配运动背心练习 2：用 forEach 打印清单
用 forEach 打印每套穿搭，格式是“1. 马甲三件套（gentleman）”。
提示：回调函数要用到两个参数，元素和下标。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
looks.forEach((look, index) => {
console.log(`${index + 1}. ${look.name}（${look.world}）`);
});运行结果：
1. 马甲三件套（gentleman）
2. 白衬衫配牛津皮鞋（gentleman）
3. Baggy 裤配 Vans（street）
4. Oversize 卫衣（street）
5. 泰拳短裤训练装（thai）
6. 绑手带配运动背心（thai）练习 3：用 map 生成标题列表
用 map 生成一个新数组 titles，每一项是“Look 1 · 马甲三件套”这样的标题，然后输出这个数组。再输出一次 looks[0]，确认原数组没有被改变。
提示：回调函数返回一个模板字符串。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const titles = looks.map((look, index) => `Look ${index + 1} · ${look.name}`);
console.log(titles);
console.log(looks[0]);运行结果：
[
'Look 1 · 马甲三件套',
'Look 2 · 白衬衫配牛津皮鞋',
'Look 3 · Baggy 裤配 Vans',
'Look 4 · Oversize 卫衣',
'Look 5 · 泰拳短裤训练装',
'Look 6 · 绑手带配运动背心'
]
{ name: '马甲三件套', world: 'gentleman', color: '#2f3e46' }练习 4：用 filter 筛出街头
用 filter 筛出所有 world 是 street 的穿搭，存进 streetLooks，输出它有几套，再用 forEach 输出每一套的名字和颜色。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const streetLooks = looks.filter((look) => look.world === "street");
console.log(`街头一共 ${streetLooks.length} 套`);
streetLooks.forEach((look) => {
console.log(`${look.name}，主色 ${look.color}`);
});运行结果：
街头一共 2 套
Baggy 裤配 Vans，主色 #3a5a80
Oversize 卫衣，主色 #e07a5f练习 5：用 find 按名字查找，并处理找不到的情况
写一个函数 findLook(name)，用 find 在 looks 里找名字完全相同的那套，返回找到的对象。调用它两次：一次找“Oversize 卫衣”，一次找“西装外套”。找到了输出“找到了：名字，属于 世界”，找不到输出“没有这套：名字”。
提示：函数里只负责 find 和 return。判断找没找到放在调用的地方，用 if 检查返回值是不是 undefined，也可以直接写 if (result)，因为 undefined 是假值。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
function findLook(name) {
return looks.find((look) => look.name === name);
}
const names = ["Oversize 卫衣", "西装外套"];
names.forEach((name) => {
const result = findLook(name);
if (result) {
console.log(`找到了：${result.name}，属于 ${result.world}`);
} else {
console.log(`没有这套：${name}`);
}
});运行结果：
找到了：Oversize 卫衣，属于 street
没有这套：西装外套练习 6：写一个按世界筛选的函数
写函数 looksOf(world)，返回属于这个世界的所有穿搭（数组）。然后对 gentleman、street、thai、snooker 四个值分别调用，输出“gentleman：2 套”这样的四行。
提示：把四个世界名放进一个数组，用 forEach 遍历它，在回调里调用 looksOf，取返回数组的 length。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
function looksOf(world) {
return looks.filter((look) => look.world === world);
}
const worlds = ["gentleman", "street", "thai", "snooker"];
worlds.forEach((world) => {
console.log(`${world}：${looksOf(world).length} 套`);
});运行结果：
gentleman：2 套
street：2 套
thai：2 套
snooker：0 套snooker 不是一个世界，filter 返回空数组，长度是 0，程序不会出错。这就是“filter 永远返回数组”的好处。
练习 7：链式调用
用一条 filter 接 map 的链式调用，得到“泰风穿搭的名字”数组并输出。再用 map 接 includes，判断 looks 里有没有 world 是 thai 的穿搭，输出 true 或 false。
提示：第二问可以先 looks.map((look) => look.world) 得到所有世界名组成的数组，再对它调用 includes("thai")。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const thaiNames = looks
.filter((look) => look.world === "thai")
.map((look) => look.name);
console.log(thaiNames);
const hasThai = looks.map((look) => look.world).includes("thai");
console.log(hasThai);运行结果：
[ '泰拳短裤训练装', '绑手带配运动背心' ]
true练习 8：增加和删除一套穿搭
用 push 在 looks 末尾加一套新的绅士穿搭：名字“斯诺克马甲配领结”，颜色 "#1b3a2f"。输出数组长度和最后一套的名字。然后用 splice 删掉下标为 1 的那套，再输出所有名字。
提示：splice(1, 1) 表示从下标 1 开始删 1 个。输出所有名字可以用 map。
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
looks.push({ name: "斯诺克马甲配领结", world: "gentleman", color: "#1b3a2f" });
console.log(looks.length);
console.log(looks[looks.length - 1].name);
looks.splice(1, 1);
console.log(looks.map((look) => look.name));运行结果：
7
斯诺克马甲配领结
[
'马甲三件套',
'Baggy 裤配 Vans',
'Oversize 卫衣',
'泰拳短裤训练装',
'绑手带配运动背心',
'斯诺克马甲配领结'
]“白衬衫配牛津皮鞋”被删掉了，后面的元素都往前挪了一位。练习完把这几行删掉或注释掉，不要影响前面的练习结果。
练习 9：用数组重写 formatDate
在 day16-weekday.js 里，用上午第 1 节的 weekdays 数组重写昨天的 weekdayName 和 formatDate，再测试 2026 年 10 月 1 日和 2026 年 12 月 25 日。
learn/js/day16-weekday.js
const weekdays = ["周日", "周一", "周二", "周三", "周四", "周五", "周六"];
function formatDate(date) {
const month = date.getMonth() + 1;
const dayOfMonth = date.getDate();
const weekday = weekdays[date.getDay()];
return `${month}月${dayOfMonth}日 ${weekday}`;
}
console.log(formatDate(new Date(2026, 9, 1)));
console.log(formatDate(new Date(2026, 11, 25)));运行结果：
10月1日 周四
12月25日 周五这里连 weekdayName 函数都省了，直接用 weekdays[date.getDay()] 查表。
提交到 Git
cd ~/code/learn
git add js
git commit -m "DAY 16：数组练习"
git pushnode day16-looks.js 运行后没有报错。明天 DAY 17 学对象：你会把四个平台做成对象数组，并写一个按名称查找平台的函数。arr[arr.length]。下标从 0 开始，最后一个是 arr[arr.length - 1]。for 循环的条件同理，写 i < arr.length，不要写 <=。console.log 看看那个值，再用 if 判断找没找到。looks.map((look) => { look.name })。去掉花括号，或者补上 return。looks.filter(...).name 是 undefined，因为 filter 返回的是数组。要一个就用 find，或者从 filter 的结果里用下标取。{ } 后面要有英文逗号，每个“名字: 值”之间也要有英文逗号。map 和 forEach 有什么区别？什么时候用 filter，什么时候用 find？
两者都会对每个元素调用一次回调函数。forEach 只是“做事”，自己返回 undefined；map 会收集每次回调的返回值，返回一个一样长的新数组。想把每一项转换成别的样子（比如取出所有名字）用 map，只想对每一项做件事（比如打印）用 forEach。
要“所有符合条件的”用 filter，结果是数组，可能为空；只要“第一个符合条件的”用 find，结果是那个元素本身，找不到是 undefined。比如“所有街头穿搭”用 filter，“名字叫 Oversize 卫衣的那一套”用 find。
filter 一个都没筛到时返回什么？find 一个都没找到时返回什么？写代码时分别要注意什么？
filter 返回空数组 []，对它取 length、再 map 都不会报错，只是结果为空，页面上可能需要显示“暂无内容”。find 返回 undefined，如果直接读它的属性会报 TypeError，所以使用前要先用 if 判断是否找到。
platforms 里有 4 个平台，platforms[4] 得到什么？不管数组多长都能取到最后一个元素的写法是什么？
得到 undefined，因为下标从 0 开始，4 个元素的下标是 0 到 3，没有 4。通用写法是 platforms[platforms.length - 1]。
console.log、looks.push 都是对象的方法。Object.keys、Object.values、Object.entries 遍历对象。... 合并数组、复制并修改对象，并解释“两个变量指向同一个对象”是怎么回事。昨天你已经用过对象了：每套穿搭都是 { name: ..., world: ..., color: ... }。今天把它讲透。
数组像一排编了号的衣架，按顺序放东西，用 0、1、2 去取。对象像一张档案卡，每一栏都有自己的标签：姓名、所属世界、给人的感觉。你不关心它是第几栏，只关心标签叫什么。一件东西有好几条不同的信息时，就用对象来装。
比如“泰风”这个世界，后面做数据库时它会有 slug、name、feeling 这几个字段，现在先用对象表示：
const thai = {
slug: "thai",
name: "泰风",
feeling: "被保护感",
sports: ["泰拳"],
};
console.log(thai);
console.log(thai.name);
console.log(thai.sports[0]);运行结果：
{ slug: 'thai', name: '泰风', feeling: '被保护感', sports: [ '泰拳' ] }
泰风
泰拳{ } 创建一个对象。里面每一行是一个属性：冒号左边是属性名（也叫“键”），右边是属性值，属性之间用逗号隔开。slug 是网址里用的英文短名，比如以后三个世界的详情页网址会是 /world/thai。thai.sports[0] 从左往右读：先取 sports 属性（一个数组），再取它的第一个元素。数组和对象什么时候用哪个？看你打算怎么“找”里面的东西：
| 数组 | 对象 | |
|---|---|---|
| 怎么取 | 按位置：looks[0] | 按名字：thai.feeling |
| 适合装 | 一串同类的东西，顺序有意义 | 一件东西的多条不同信息 |
| 例子 | 四个平台、六套穿搭、六道题 | 一个平台的名称、链接、颜色 |
实际项目里两者几乎总是配合使用：数组里装对象，对象里又有数组，就像上面的 thai 对象里装着 sports 数组。
读取属性有两种写法：
const thai = { slug: "thai", name: "泰风", feeling: "被保护感" };
console.log(thai.feeling);
console.log(thai["feeling"]);
const key = "name";
console.log(thai[key]);
console.log(thai.key);运行结果：
被保护感
被保护感
泰风
undefinedthai.feeling：点号写法，点后面直接写属性名。简洁，平时首选。thai["feeling"]：方括号写法，方括号里是一个字符串，效果一样。thai[key]：方括号里放的是变量 key，JavaScript 先取出 key 的值 "name"，再去找 name 属性，所以得到“泰风”。thai.key：点号后面的字会被当成属性名本身，它去找一个叫 key 的属性，没有，所以是 undefined。这就引出了今晚验收题的答案。方括号在两种情况下是必须的：
look["best-look"]。点号写法 look.best-look 会被理解成“look.best 减去 look”，当然不对。添加、修改、删除属性也很直接：
const street = { slug: "street", name: "街头" };
street.feeling = "心动";
street.name = "街头线";
console.log(street);
delete street.name;
console.log(street);
console.log(street.color);
console.log("feeling" in street);运行结果：
{ slug: 'street', name: '街头线', feeling: '心动' }
{ slug: 'street', feeling: '心动' }
undefined
truedelete 删除一个属性。"feeling" in street 检查对象里有没有这个属性，得到 true 或 false。和数组一样，用 const 声明的对象，里面的属性可以随便改，只是不能把整个变量换成另一个对象。
属性值可以是任何类型，当然也可以是函数。放在对象里的函数叫方法，它表示这个对象“能做什么”：
const dongge = {
name: "东哥",
worlds: ["绅士", "街头", "泰风"],
sayGoodnight() {
console.log("晚安，三岁。");
},
};
dongge.sayGoodnight();
console.log(dongge.worlds.length);运行结果：
晚安，三岁。
3sayGoodnight() { ... } 是在对象里写方法的简写，调用时用点号加圆括号。方法里如果想用到对象自己的其他属性，需要一个叫 this 的关键字，它的规则比较绕，本课表暂时用不到，以后遇到再讲。现在回头看，你其实从 DAY 13 起就在用方法了：
console.log()：console 是 JavaScript 自带的一个对象，log 是它的方法。Math.floor()：Math 对象的 floor 方法。looks.push()、looks.map()：每个数组都自带的方法。"Vans".includes("V")：字符串也有方法。区分属性和方法：属性是“它有什么”，读取时不带括号，比如 looks.length、thai.name；方法是“它能做什么”，调用时要带括号，比如 looks.push(...)。DAY 19 操作网页时，你会遇到大量这样的属性和方法。
假设你统计了四个平台按钮的点击次数，用一个对象来存，属性名是平台，属性值是次数：
const clicks = { xiaohongshu: 120, tiktok: 86, facebook: 15, instagram: 42 };
for (const key in clicks) {
console.log(`${key}：${clicks[key]} 次`);
}运行结果：
xiaohongshu：120 次
tiktok：86 次
facebook：15 次
instagram：42 次for...in 会把对象的每个属性名依次交给 key。注意 key 是一个存着属性名的变量，所以取值必须用方括号 clicks[key]，写成 clicks.key 就错了，这正是第 2 节讲的情况。
另一种办法是先把对象“转成数组”，再用你昨天学的数组方法处理。JavaScript 提供了三个工具：
const clicks = { xiaohongshu: 120, tiktok: 86, facebook: 15, instagram: 42 };
console.log(Object.keys(clicks));
console.log(Object.values(clicks));
console.log(Object.entries(clicks));运行结果：
[ 'xiaohongshu', 'tiktok', 'facebook', 'instagram' ]
[ 120, 86, 15, 42 ]
[
[ 'xiaohongshu', 120 ],
[ 'tiktok', 86 ],
[ 'facebook', 15 ],
[ 'instagram', 42 ]
]Object.keys()：所有属性名组成的数组。Object.values()：所有属性值组成的数组。想算总点击数，对它求和就行。Object.entries()：每个属性变成一个 [属性名, 属性值] 的小数组，再装进一个大数组。名字和值都要用时最方便，第 6 节会教你怎么优雅地拆开它们。for...in 和 Object 这三个工具效果差不多，怎么选？只是简单地走一遍，两种都行；想接着用数组方法处理，比如“只保留点击超过 50 次的平台”，就先用 Object.entries 转成数组，再接 filter 或 map。本课表后面更常用后者。
比如算总点击数：
const clicks = { xiaohongshu: 120, tiktok: 86, facebook: 15, instagram: 42 };
let total = 0;
for (const count of Object.values(clicks)) {
total += count;
}
console.log(`四个平台一共被点了 ${total} 次`);运行结果：
四个平台一共被点了 263 次下午的主角是平台列表：四个平台，每个有名称、链接、颜色三条信息。这是昨天学的“对象数组”：
learn/js/day17-platforms.js
const platforms = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#000000" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e4405f" },
];
console.log(platforms.map((platform) => platform.name));
console.log(platforms[1].url);运行结果：
[ '小红书', 'TikTok', 'Facebook', 'Instagram' ]
https://example.com/tiktok链接用的是 example.com 的占位地址，练习时可以换成你自己的主页链接，和链接主页上用的保持一致。颜色是各平台常见的品牌主色，你可以按自己的设计调整。
这种“数组里装着一个个对象”的数据，你以后会天天见到。DAY 22 你会把平台数据挪进一个叫 data.json 的文件，里面的格式几乎和上面这段一模一样；DAY 42 从数据库里读出来的 looks，到了 JavaScript 里也是这个形状。今天把它写熟，后面会轻松很多。
对象数组适合“一串有顺序的同类东西”，比如要按顺序显示在页面上的按钮。但如果你经常要“根据一个名字直接拿到对应的数据”，还有另一种形状更顺手：用对象当“查找表”，属性名就是查找用的名字。
const worlds = {
gentleman: { name: "绅士", feeling: "安全感" },
street: { name: "街头", feeling: "心动" },
thai: { name: "泰风", feeling: "被保护感" },
};
const slug = "street";
console.log(worlds[slug].feeling);
console.log(worlds.thai.name);运行结果：
心动
泰风用对象数组的话，你得 find 一遍才能找到街头；用查找表，worlds[slug] 一步到位。这里的方括号又是必须的，因为 slug 是变量。明天的计分程序会同时用到这两种形状：题目用对象数组（有顺序），三个世界的信息用查找表（按名字取）。
为什么需要它：一段代码里如果反复写 world.name、world.feeling、world.slug，前缀重复得让人眼花。更常见的情况是，一个函数拿到一个对象，只关心其中两三个属性。解构就是“一次把需要的属性取出来，放进同名的变量”：
const world = { slug: "thai", name: "泰风", feeling: "被保护感" };
const { name, feeling } = world;
console.log(name, feeling);运行结果：
泰风 被保护感const { name, feeling } = world; 等于下面两行的合写：const name = world.name; 和 const feeling = world.feeling;。左边的花括号不是在创建对象，而是在说“从右边的对象里，按名字拆出这几个属性”，所以叫“解构”。
还可以顺便改名、设默认值：
const world = { slug: "thai", name: "泰风", feeling: "被保护感" };
const { name: worldName, color = "#b5121f" } = world;
console.log(worldName, color);运行结果：
泰风 #b5121fname: worldName 表示“取出 name 属性，放进叫 worldName 的变量”。color = "#b5121f" 表示“取出 color，如果没有这个属性，就用默认值”。
数组也能解构，只不过是按位置取，用方括号：
const platforms = ["小红书", "TikTok", "Facebook", "Instagram"];
const [first, second] = platforms;
console.log(first, second);运行结果：
小红书 TikTok数组解构和 Object.entries 是绝配，每一项 [名字, 值] 刚好拆成两个变量：
const clicks = { xiaohongshu: 120, tiktok: 86 };
for (const [platform, count] of Object.entries(clicks)) {
console.log(`${platform}：${count}`);
}运行结果：
xiaohongshu：120
tiktok：86解构还能直接写在函数的参数位置。函数接收一个对象，参数里直接拆出需要的属性：
function describe({ name, feeling }) {
return `${name}，给你${feeling}`;
}
console.log(describe({ slug: "gentleman", name: "绅士", feeling: "安全感" }));运行结果：
绅士，给你安全感这个写法请一定看熟。DAY 27 学 React 时，每个组件都是这样接收数据的。
三个点 ... 叫展开运算符，作用是“把里面的东西一个个倒出来”。用在数组上，可以合并数组：
const mainWorlds = ["绅士", "街头", "泰风"];
const specials = ["三岁时刻", "三岁换装"];
const allShows = [...mainWorlds, ...specials];
console.log(allShows);
console.log(mainWorlds.length);运行结果：
[ '绅士', '街头', '泰风', '三岁时刻', '三岁换装' ]
3注意 mainWorlds 本身没有变，还是 3 个元素。对比昨天的 push：mainWorlds.push("三岁时刻") 会直接改掉原数组，而 [...mainWorlds, "三岁时刻"] 是生成一个新数组，原数组保持不动。
用在对象上，可以复制一个对象，并顺便改掉其中某些属性。写在后面的同名属性会覆盖前面的：
const base = { name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" };
const updated = { ...base, url: "https://example.com/new-home" };
console.log(updated.url);
console.log(base.url);运行结果：
https://example.com/new-home
https://example.com/xiaohongshu为什么要这么麻烦地复制，而不是直接改 base.url？这就要讲一个非常重要、也非常容易踩坑的概念：
const a = { name: "绅士" };
const b = a;
b.name = "街头";
console.log(a.name);
const c = { ...a };
c.name = "泰风";
console.log(a.name);
console.log(a === b, a === c);运行结果：
街头
街头
true false明明改的是 b，a 也跟着变了。原因是：对象存进变量时，变量里放的不是对象本身，而是“这个对象在哪里”，好比一把柜子的钥匙。const b = a; 只是配了一把钥匙，两把钥匙开的是同一个柜子，所以用 b 改了柜子里的东西，用 a 打开看到的也变了。
{ ...a } 则是新做了一个柜子，把 a 柜子里的东西一件件搬进去。改新柜子，不影响旧柜子。=== 比较两个对象时，比的是“是不是同一个柜子”，所以 a 和 b 相等，a 和 c 不相等，哪怕 c 刚复制出来时内容和 a 一模一样。数组也是一样的道理。
“不直接修改原来的数据，而是复制一份再改”，是 DAY 29 学 React 状态时的核心规则。今天先在练习里体会一次。明天 DAY 18 是本周综合练习，你会把这周学的全部串起来，写一个文字版的测试小游戏。
准备今天的练习文件
cd ~/code/learn/js
touch day17-worlds.js day17-platforms.js day17-clicks.js
code .练习 1：三个世界的对象
在 day17-worlds.js 里，写一个数组 worlds，装三个对象，每个对象有 slug、name、feeling 三个属性（gentleman 绅士 安全感、street 街头 心动、thai 泰风 被保护感）。用 forEach 输出“绅士（gentleman）：安全感”这样的三行，回调函数的参数用解构写法。
提示：回调可以写成 ({ slug, name, feeling }) => { ... }，注意外面那对圆括号不能省。
learn/js/day17-worlds.js
const worlds = [
{ slug: "gentleman", name: "绅士", feeling: "安全感" },
{ slug: "street", name: "街头", feeling: "心动" },
{ slug: "thai", name: "泰风", feeling: "被保护感" },
];
worlds.forEach(({ slug, name, feeling }) => {
console.log(`${name}（${slug}）：${feeling}`);
});运行结果：
绅士（gentleman）：安全感
街头（street）：心动
泰风（thai）：被保护感练习 2：读写属性
在同一个文件末尾继续写：取出 worlds 里的泰风对象，给它添加一个属性 sport，值是 "泰拳"；再用一个变量 field = "feeling"，通过方括号读出泰风的 feeling。最后输出整个泰风对象。
const worlds = [
{ slug: "gentleman", name: "绅士", feeling: "安全感" },
{ slug: "street", name: "街头", feeling: "心动" },
{ slug: "thai", name: "泰风", feeling: "被保护感" },
];
const thai = worlds[2];
thai.sport = "泰拳";
const field = "feeling";
console.log(thai[field]);
console.log(thai);
console.log(worlds[2].sport);运行结果：
被保护感
{ slug: 'thai', name: '泰风', feeling: '被保护感', sport: '泰拳' }
泰拳最后一行也输出了“泰拳”：thai 和 worlds[2] 是同一个柜子的两把钥匙，用 thai 添加的属性，从 worlds[2] 也能看到。
练习 3：四个平台的对象数组
在 day17-platforms.js 里写好上午第 5 节的 platforms 数组（名称、链接、颜色）。链接可以换成你自己的主页。用 forEach 输出“小红书 → 链接”这样的四行，回调参数用解构。
learn/js/day17-platforms.js
const platforms = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#000000" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e4405f" },
];
platforms.forEach(({ name, url }) => {
console.log(`${name} → ${url}`);
});运行结果：
小红书 → https://example.com/xiaohongshu
TikTok → https://example.com/tiktok
Facebook → https://example.com/facebook
Instagram → https://example.com/instagram练习 4：按名称查找平台
在 platforms 下面写函数 findPlatform(name)：返回名称相同的那个平台对象，找不到返回 undefined。分别用 "TikTok" 和 "YouTube" 测试，找到时输出它的链接和颜色，找不到时输出“没有这个平台：YouTube”。
提示：函数里一行 find 就够了。判断找没找到放在调用的地方。
const platforms = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#000000" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e4405f" },
];
function findPlatform(name) {
return platforms.find((platform) => platform.name === name);
}
const tests = ["TikTok", "YouTube"];
tests.forEach((name) => {
const found = findPlatform(name);
if (found) {
console.log(`${found.name}：${found.url}，颜色 ${found.color}`);
} else {
console.log(`没有这个平台：${name}`);
}
});运行结果：
TikTok：https://example.com/tiktok，颜色 #000000
没有这个平台：YouTube练习 5：让查找不区分大小写
访客或者你自己输入时，可能写成 "tiktok" 或 "INSTAGRAM"。改进 findPlatform，让它不区分英文大小写。用 "tiktok"、"INSTAGRAM"、"小红书" 测试。
提示：字符串的 toLowerCase() 方法会返回全部转成小写的新字符串，比如 "TikTok".toLowerCase() 得到 "tiktok"。比较前把两边都转成小写。中文没有大小写，转换后不变。
const platforms = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#000000" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e4405f" },
];
function findPlatform(name) {
const target = name.toLowerCase();
return platforms.find((platform) => platform.name.toLowerCase() === target);
}
console.log(findPlatform("tiktok").name);
console.log(findPlatform("INSTAGRAM").name);
console.log(findPlatform("小红书").url);运行结果：
TikTok
Instagram
https://example.com/xiaohongshu这里为了简短，直接在返回值上读了 name。实际使用时，如果查的名字可能不存在，还是要像练习 4 那样先判断。
练习 6：解构查找结果，并防住找不到的情况
先试一下这行代码会怎样（在 findPlatform 下面写，运行后看报错，然后删掉）：
const { url } = findPlatform("YouTube");你会看到 TypeError: Cannot destructure property 'url' of 'findPlatform(...)' as it is undefined.，意思是“没法从 undefined 里拆出 url”。现在写一个函数 linkOf(name)：找到平台就用解构取出 url 并返回；找不到就返回字符串 "#"（页面上的空链接）。
提示：先用一个变量接住 findPlatform 的结果，用 if 判断，找不到就提前 return "#"。
const platforms = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#000000" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e4405f" },
];
function findPlatform(name) {
const target = name.toLowerCase();
return platforms.find((platform) => platform.name.toLowerCase() === target);
}
function linkOf(name) {
const found = findPlatform(name);
if (!found) {
return "#";
}
const { url } = found;
return url;
}
console.log(linkOf("facebook"));
console.log(linkOf("YouTube"));运行结果：
https://example.com/facebook
#if (!found) 读作“如果没找到”。这种“先把异常情况处理掉并提前 return，剩下的代码只处理正常情况”的写法，会让函数更好读。
练习 7：点击统计
在 day17-clicks.js 里，用上午第 4 节的 clicks 对象，完成两件事：算出总点击数；找出点击最多的平台和它的次数。
提示：第二问用 Object.entries 配合 for...of 和数组解构遍历。在循环外准备两个 let 变量，记录“目前最多的平台”和“目前最多的次数”（次数从 0 开始），每一轮如果当前次数更大，就更新这两个变量。
learn/js/day17-clicks.js
const clicks = { xiaohongshu: 120, tiktok: 86, facebook: 15, instagram: 42 };
let total = 0;
for (const count of Object.values(clicks)) {
total += count;
}
console.log(`总点击：${total}`);
let topPlatform = "";
let topCount = 0;
for (const [platform, count] of Object.entries(clicks)) {
if (count > topCount) {
topPlatform = platform;
topCount = count;
}
}
console.log(`点击最多：${topPlatform}，${topCount} 次`);运行结果：
总点击：263
点击最多：xiaohongshu，120 次“找最大值”的这个套路，明天计算得分最高的世界时还会用到。想一想：如果有两个平台点击数一样多，这段代码会选哪一个？明天的验收题就问这个。
练习 8：用展开运算符修改一个平台，不动原数组
回到 day17-platforms.js。假设你的 TikTok 主页换了地址。用 map 生成一个新数组 updatedPlatforms：名称是 TikTok 的那一项，换成一个复制出来、url 改成 "https://example.com/tiktok-new" 的新对象；其他项原样保留。最后分别输出新旧数组里 TikTok 的 url。
提示：map 的回调里用三元运算符：条件 ? { ...platform, url: 新地址 } : platform。
const platforms = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#000000" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e4405f" },
];
const updatedPlatforms = platforms.map((platform) =>
platform.name === "TikTok" ? { ...platform, url: "https://example.com/tiktok-new" } : platform
);
console.log(updatedPlatforms[1].url);
console.log(platforms[1].url);
console.log(updatedPlatforms[0] === platforms[0]);运行结果：
https://example.com/tiktok-new
https://example.com/tiktok
true最后一行是 true：没改的平台直接沿用原来的对象，只有 TikTok 是新做的柜子。这个写法看起来有点绕，但 DAY 29 学 React 时你会经常写它，今天先混个脸熟。
练习 9：三个世界的查找表
在 day17-worlds.js 末尾，写一个以 slug 为属性名的查找表 worldsBySlug（形状见上午第 5 节），再写函数 feelingOf(slug)：返回这个世界的 feeling，如果 slug 不存在就返回 "未知世界"。用 "gentleman"、"thai"、"snooker" 测试。
提示：worldsBySlug[slug] 找不到时是 undefined，先判断再读 feeling。
const worldsBySlug = {
gentleman: { name: "绅士", feeling: "安全感" },
street: { name: "街头", feeling: "心动" },
thai: { name: "泰风", feeling: "被保护感" },
};
function feelingOf(slug) {
const world = worldsBySlug[slug];
if (!world) {
return "未知世界";
}
return world.feeling;
}
console.log(feelingOf("gentleman"));
console.log(feelingOf("thai"));
console.log(feelingOf("snooker"));运行结果：
安全感
被保护感
未知世界提交到 Git
cd ~/code/learn
git add js
git commit -m "DAY 17：对象练习与平台查找"
git pushobj.key。属性名在变量里时必须用方括号 obj[key]。for...in 循环里最容易犯这个错。const b = a;。需要独立的一份时，用 { ...a } 复制。({ name }) => name，不能写 { name } => name。{ name = "绅士" }。对象里是“名字: 值”，用冒号。user.name 和 user["name"] 分别在什么时候用？
两者读的是同一个属性。属性名是固定的、合法的变量名时，用点号，简洁好读，这是首选。以下两种情况必须用方括号：一是属性名存在变量里，比如 const key = "name"; user[key]，写成 user.key 会去找一个叫 key 的属性；二是属性名不是合法的变量名，比如带短横线或空格的 user["nick-name"]。
下面的代码输出什么？为什么？
const look = { name: "马甲三件套" };
const copy = look;
copy.name = "Oversize 卫衣";
console.log(look.name);输出 Oversize 卫衣。const copy = look; 没有复制对象，只是让 copy 和 look 指向同一个对象，就像同一个柜子配了两把钥匙。通过 copy 修改，look 看到的也变了。想要独立的一份，应该写 const copy = { ...look };。
const { url } = findPlatform("YouTube"); 运行时会发生什么？怎么改才安全？
platforms 里没有 YouTube，findPlatform 返回 undefined，对 undefined 解构会报 TypeError，程序停止。安全的写法是先用变量接住结果，判断找到了再解构：
const found = findPlatform("YouTube");
if (found) {
const { url } = found;
console.log(url);
} else {
console.log("没有这个平台");
}~/code/learn/js/quiz-cli.js，用 node quiz-cli.js 运行，算出得分最高的世界。> 比较的计分函数会怎样，并把它改成把并列的世界都找出来。五天前，你还不知道 console.log 是什么。现在你已经掌握了 JavaScript 最核心的六块积木。今天上午先复习，把它们摆在一起看清楚；下午用它们搭一个完整的小程序。
| 积木 | 一句话 | 例子 |
|---|---|---|
| 变量与类型（DAY 13） | 给数据贴标签；数据有数字、字符串、布尔值等类型 | const brand = "三岁的东哥"; |
| 运算与转换（DAY 13） | 加减乘除和比较；+ 遇到字符串会变成拼接 | "5" + 3 得到 "53" |
| 条件（DAY 14） | 根据真假走不同的路 | if (followers >= 10000) { ... } |
| 循环（DAY 14） | 重复做事，知道次数用 for，只知道停止条件用 while | for (let i = 1; i <= 5; i++) |
| 函数（DAY 15） | 参数进，return 出，写一次反复用 | formatDate(new Date()) |
| 数组（DAY 16） | 一串有顺序的东西，用 map、filter、find 处理 | looks.filter((look) => look.world === "street") |
| 对象（DAY 17） | 一件东西的多条信息，按名字取 | worlds[slug].feeling |
复习时不要只是重读笔记。更有效的办法是合上笔记，对着这张表的每一行，自己在空文件里写一个小例子并运行。写不出来的那一行，就是今天要回去补的地方。
还有一件事值得注意：这六块积木几乎从来不单独出现。昨天的“找点击最多的平台”，就同时用到了对象（clicks）、数组（Object.entries 的结果）、循环（for...of）、条件（if）和变量（topCount）。今天下午的测试小游戏会把它们全部用上。
上午的另一项任务，是请 Claude 根据你的笔记出 10 道综合题。这一阶段 Claude 是你的老师，好老师出题、批改、追问，但不替你答题。所以提示词里要把规则说清楚：
答题时，“读代码写输出”的题先在纸上写答案，再复制代码到控制台运行验证。答错的题目记进错题本，每道写三栏：
| 我以为 | 实际 | 原因 |
|---|---|---|
looks.find(...) 找不到会返回空数组 | 返回 undefined | find 返回的是“那一个元素”，不是数组；返回数组的是 filter |
“原因”那一栏最重要。能用自己的话写出原因，下次就不会再错。
下午要做的是一个文字版的测试：“你最需要哪个东哥”。访客回答 6 道题，每道题有 3 个选项，每个选项对应一个世界。答完后，看哪个世界得分最高，就告诉她最需要哪个世界的东哥。今天还没有网页，答案先固定写在代码里，程序在终端里运行，输出结果。DAY 23 你会把它做成真正能在手机上点的网页小游戏。
第一次写“大一点”的程序，最容易犯的错是打开编辑器就开始敲。正确的做法是先用中文把步骤列出来，这种用人话写的步骤叫“伪代码”：
1. 准备数据：三个世界的信息、六道题、一组固定的答案
2. 检查答案：数量对不对，每个答案是不是有效的选项
3. 计分：每个世界从 0 分开始，逐题看选了哪个选项，给它对应的世界加 1 分
4. 找最高分：哪个世界分最多？如果并列，怎么办？
5. 输出：显示得分，以及最需要的世界和一句话这五步，每一步都是你这周学过的东西：第 1 步是对象和数组，第 2 步是循环和条件，第 3 步是遍历和对象的方括号读写，第 4 步是找最大值，第 5 步是模板字符串。每一步写成一个函数，逐个写、逐个测，最后在主流程里按顺序调用。这样即使出了错，你也能很快知道是哪一步错了。
// 3. 计分，然后在每条注释下面填代码。写完之后，注释还能帮以后的你读懂这个文件。程序好不好写，一大半取决于数据设计得好不好。我们用昨天学的两种形状：
[2, 1, ...] 表示第 1 题选了下标 2 的选项，第 2 题选了下标 1 的选项。先用一道题看看怎么从答案找到世界：
const questions = [
{
text: "周末下午，你更想去哪里？",
options: [
{ text: "安静的球房", world: "gentleman" },
{ text: "滑板公园", world: "street" },
{ text: "拳馆", world: "thai" },
],
},
];
const answers = [2];
const question = questions[0];
const chosen = question.options[answers[0]];
console.log(question.text);
console.log(chosen.text);
console.log(chosen.world);运行结果：
周末下午，你更想去哪里？
拳馆
thai关键是 question.options[answers[0]] 这一句，从里往外读：answers[0] 是 2；question.options[2] 是第三个选项；它的 world 是 thai。选项里存的是 world 的 slug，而不是“泰风”这样的中文名，因为 slug 可以直接拿去查找表里取信息，中文名、感觉、一句话都在查找表里，只需要写一次。
为什么答案存下标，而不是直接存 "thai"？因为将来在网页上，访客点的是“第几个按钮”，存下标最自然；而且题目的选项文字改了，答案也不用跟着改。
计分就是：准备一个记分板对象，三个世界都从 0 开始；然后逐题看选了哪个选项，给那个选项对应的世界加 1 分。用两道题演示，并把每一步打印出来：
const questions = [
{
text: "周末下午，你更想去哪里？",
options: [
{ text: "安静的球房", world: "gentleman" },
{ text: "滑板公园", world: "street" },
{ text: "拳馆", world: "thai" },
],
},
{
text: "哪个瞬间最容易打动你？",
options: [
{ text: "他瞄准时专注的那几秒", world: "gentleman" },
{ text: "他摔了之后冲镜头笑", world: "street" },
{ text: "他训练完安静地收拾手带", world: "thai" },
],
},
];
const answers = [2, 2];
const scores = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((answerIndex, questionIndex) => {
const option = questions[questionIndex].options[answerIndex];
console.log(`第 ${questionIndex + 1} 题选了：${option.text}（${option.world}）`);
scores[option.world]++;
});
console.log(scores);运行结果：
第 1 题选了：拳馆（thai）
第 2 题选了：他训练完安静地收拾手带（thai）
{ gentleman: 0, street: 0, thai: 2 }questions[questionIndex] 找到这道题，再用 .options[answerIndex] 找到选中的选项。scores[option.world]++ 是今天最关键的一行。option.world 是一个存着 "thai" 的值，要用它当属性名去改记分板，就必须用方括号，这就是 DAY 17 的验收题。整句等于 scores["thai"] = scores["thai"] + 1。下午你会把这段包进一个函数 calcScores(questions, answers)，让它 return 记分板，而不是在里面打印。为什么不在里面打印？还记得 DAY 15 的习惯吗：一个函数只做一件事。calcScores 只负责算分，算出来的记分板交给别人决定怎么用：今天是在终端里打印，DAY 23 是显示在网页上，DAY 51 是交给自动测试去检查。它自己一行都不用改。
有了记分板，下一步是找出分最高的世界。昨天“找点击最多的平台”的写法可以直接套用：
function findTopWorld(scores) {
let topSlug = "";
let topScore = -1;
for (const [slug, score] of Object.entries(scores)) {
if (score > topScore) {
topSlug = slug;
topScore = score;
}
}
return topSlug;
}
console.log(findTopWorld({ gentleman: 1, street: 2, thai: 3 }));
console.log(findTopWorld({ gentleman: 3, street: 3, thai: 0 }));
console.log(findTopWorld({ street: 3, gentleman: 3, thai: 0 }));运行结果：
thai
gentleman
street第一行没问题。看第二、三行：绅士和街头都是 3 分，结果却取决于谁在对象里排在前面。因为比较用的是 >（严格大于），第二个 3 分不比第一个 3 分“大”，所以不会替换，先出现的那个赢了。记分板里属性的顺序只是写代码时碰巧的顺序，和访客的回答毫无关系。这样的结果对访客不公平，这个问题就是今晚验收题。
应该怎样？没有唯一正确的答案，但必须是你有意识地做出的规定，而不是碰巧的结果。常见的规定有三种：
我们选第一种。思路分两步：先算出最高分是多少，再把所有等于最高分的世界筛出来。这里要用到两个新工具。第一个是 Math.max()，它返回几个数字里最大的那个，但它不接受数组，要用 DAY 17 学的展开运算符把数组“倒出来”：
const values = [1, 2, 3];
console.log(Math.max(1, 2, 3));
console.log(Math.max(values));
console.log(Math.max(...values));运行结果：
3
NaN
3第二行直接把数组交给它，得到 NaN；第三行加了 ...，等于写 Math.max(1, 2, 3)。有了最高分，用 filter 把分数等于它的世界都留下：
function findTopWorlds(scores) {
const maxScore = Math.max(...Object.values(scores));
return Object.keys(scores).filter((slug) => scores[slug] === maxScore);
}
console.log(findTopWorlds({ gentleman: 1, street: 2, thai: 3 }));
console.log(findTopWorlds({ gentleman: 3, street: 3, thai: 0 }));
console.log(findTopWorlds({ gentleman: 2, street: 2, thai: 2 }));运行结果：
[ 'thai' ]
[ 'gentleman', 'street' ]
[ 'gentleman', 'street', 'thai' ]函数名从 findTopWorld 变成了 findTopWorlds，多了一个 s，返回值也从一个字符串变成了数组。这是一个很好的习惯：返回的东西变了，名字也跟着变，看名字就知道它可能返回好几个。
输出结果时，要把并列的几个世界名连成一句话。数组的 join() 方法能把所有元素用你指定的符号连成一个字符串：
const names = ["绅士", "街头"];
console.log(names.join("、"));
console.log(names.join(" 和 "));运行结果：
绅士、街头
绅士 和 街头程序变长以后，报错是家常便饭。报错不是失败，而是 JavaScript 在告诉你“哪里、出了什么事”。假设答案数组里有一个 5，而每道题只有 3 个选项，计分时就会出错，终端里大致会看到这样的内容（行号以你的文件为准）：
/Users/dong/code/learn/js/quiz-cli.js:94
scores[option.world]++;
^
TypeError: Cannot read properties of undefined (reading 'world')
at /Users/dong/code/learn/js/quiz-cli.js:94:19
at Array.forEach (<anonymous>)
at calcScores (/Users/dong/code/learn/js/quiz-cli.js:92:11)读报错按这个顺序：
TypeError: Cannot read properties of undefined (reading 'world')，意思是“你想从 undefined 上读 world 属性”。也就是说，option 是 undefined。quiz-cli.js:94 表示第 94 行，下面还把那行代码和一个小箭头 ^ 画了出来，指向出事的位置。at calcScores 告诉你它发生在 calcScores 函数里。questions[questionIndex].options[answerIndex] 取出来的，它为什么会是 undefined？因为 answerIndex 是 5，而 options 只有下标 0、1、2，DAY 16 学过，越界的下标得到 undefined。推理不出来时，用 DAY 14 学的办法：在出错的那一行前面加 console.log，把 questionIndex、answerIndex、option 都打印出来，答案一目了然。
比修报错更好的是防止它发生。下午你会写一个 validateAnswers 函数，在计分之前先检查答案：数量和题目是否一致，每个答案是否在有效范围内。有问题就输出一句清楚的中文提示，而不是让程序崩在半路。“先检查输入，再做正事”，是写可靠程序的基本功，DAY 44 用 Zod 校验表单时，做的也是同一件事。
明天 DAY 19 开始学操作网页，这周写的数组、对象和函数，都会变成访客在页面上看得见的东西。
整理笔记，请 Claude 出 10 道综合题
花 30 分钟把 DAY 13 到 17 的笔记整理成一页，每天写 3 到 5 条最重要的点。然后在 Claude Code 里新开一个对话，把笔记和本页最后“问 Claude”的第一条提示词一起发过去，一题一题作答。
“读代码写输出”的题，先在纸上写答案，再把代码复制到 Chrome 控制台运行验证。答错的题按上午第 2 节的三栏格式记进错题本。
新建 quiz-cli.js，写入三个世界的数据
cd ~/code/learn/js
touch quiz-cli.js
code quiz-cli.js先把上午第 3 节的五步伪代码写成注释骨架，再在第 1 步下面写三个世界的查找表。每个世界有名字、感觉和一句话，一句话来自你旧官网上三个世界的描述，只说事情，不说情话：
learn/js/quiz-cli.js
// 你最需要哪个东哥：文字版测试
// 运行方法：node quiz-cli.js
// 1. 三个世界的信息：以 slug 为属性名的查找表
const worlds = {
gentleman: {
name: "绅士",
feeling: "安全感",
line: "去看绅士线：球房里安静的一小时，只有球声和呼吸。",
},
street: {
name: "街头",
feeling: "心动",
line: "去看街头线：后座视角，路线就是内容。摔了，冲镜头笑。",
},
thai: {
name: "泰风",
feeling: "被保护感",
line: "去看泰风线：打完拳，安静地收手带，给拳馆的狗添水。",
},
};写入六道题
接在 worlds 下面。你可以改成自己的题目和选项文字，但要保持结构：每道题有 text 和 3 个选项，每个选项有 text 和 world，world 只能是 gentleman、street、thai 之一。
learn/js/quiz-cli.js
// 2. 六道题：每个选项对应一个世界
const questions = [
{
text: "周末下午，你更想去哪里？",
options: [
{ text: "安静的球房", world: "gentleman" },
{ text: "滑板公园", world: "street" },
{ text: "拳馆", world: "thai" },
],
},
{
text: "哪个瞬间最容易打动你？",
options: [
{ text: "他瞄准时专注的那几秒", world: "gentleman" },
{ text: "他摔了之后冲镜头笑", world: "street" },
{ text: "他训练完安静地收拾手带", world: "thai" },
],
},
{
text: "一起出门，你希望他穿什么？",
options: [
{ text: "马甲、衬衫、皮鞋", world: "gentleman" },
{ text: "Baggy 裤配 Vans", world: "street" },
{ text: "泰拳短裤和 T 恤", world: "thai" },
],
},
{
text: "你最近最缺的是什么？",
options: [
{ text: "一点确定感", world: "gentleman" },
{ text: "一点新鲜感", world: "street" },
{ text: "一点有人撑腰的感觉", world: "thai" },
],
},
{
text: "背景音你选哪一种？",
options: [
{ text: "只有击球声", world: "gentleman" },
{ text: "鼓点和说唱", world: "street" },
{ text: "拳套的击打声", world: "thai" },
],
},
{
text: "如果一起旅行，你想去哪？",
options: [
{ text: "有老球房的城市", world: "gentleman" },
{ text: "街头文化最热闹的街区", world: "street" },
{ text: "曼谷的拳馆", world: "thai" },
],
},
];写入固定答案，先检查数据
接着写第 3 步：一组固定的答案。然后在文件最后临时加几行 console.log，确认数据能正确读到，再运行一次：
learn/js/quiz-cli.js
// 3. 一组固定的答案：每个数字是所选选项的下标
const answers = [2, 1, 2, 0, 2, 1];
// 临时检查，确认后删掉
console.log(questions.length);
console.log(questions[0].text);
console.log(questions[0].options[answers[0]].text);node quiz-cli.js写 calcScores：计分函数
写函数 calcScores(questions, answers)：创建记分板，三个世界从 0 开始，遍历答案给对应的世界加分，最后 return 记分板。函数里不要 console.log。
提示：把上午第 5 节的代码搬进函数，去掉里面的打印，末尾加 return scores;。写完后在文件最后临时加一行 console.log(calcScores(questions, answers)); 运行，应该看到 { gentleman: 1, street: 2, thai: 3 }。
learn/js/quiz-cli.js
// 5. 计分：返回每个世界的得分
function calcScores(questions, answers) {
const scores = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((answerIndex, questionIndex) => {
const option = questions[questionIndex].options[answerIndex];
scores[option.world]++;
});
return scores;
}对一下固定答案 [2, 1, 2, 0, 2, 1]：第 1、3、5 题选了泰风，第 2、6 题选了街头，第 4 题选了绅士，所以是绅士 1、街头 2、泰风 3。
写 findTopWorlds：先踩一次同分的坑
先按上午第 6 节的第一个版本，写只返回一个世界的 findTopWorld（用 > 比较），用 { gentleman: 3, street: 3, thai: 0 } 和 { street: 3, gentleman: 3, thai: 0 } 各测一次，亲眼看到结果随顺序变化。
然后删掉它，写正式版 findTopWorlds(scores)：返回一个数组，包含所有得分等于最高分的世界的 slug。
提示：两步。第一步用 Math.max(...Object.values(scores)) 算出最高分；第二步对 Object.keys(scores) 用 filter，留下分数等于最高分的 slug。
learn/js/quiz-cli.js
// 6. 找出得分最高的世界：同分时全部返回
function findTopWorlds(scores) {
const maxScore = Math.max(...Object.values(scores));
return Object.keys(scores).filter((slug) => scores[slug] === maxScore);
}临时加一行 console.log(findTopWorlds(calcScores(questions, answers)));，应该输出 [ 'thai' ]。
写 printResult：输出结果
写函数 printResult(topWorlds, scores)：先输出一行三个世界的得分。如果只有一个最高的世界，输出“你最需要的是泰风东哥。你现在需要的是被保护感。”和这个世界的一句话；如果有并列，输出“绅士、街头同分。不用只选一个，这几条线换着看：”，再把每个并列世界的一句话各输出一行。
提示：用 topWorlds.length === 1 判断是不是只有一个。单个世界时，用 worlds[topWorlds[0]] 从查找表取出信息，可以顺便解构。并列时，先用 map 把 slug 变成中文名，再用 join("、") 连起来。单个世界的分支输出完可以直接 return;，后面就不用写 else。
learn/js/quiz-cli.js
// 7. 输出结果
function printResult(topWorlds, scores) {
console.log(`得分：绅士 ${scores.gentleman}，街头 ${scores.street}，泰风 ${scores.thai}`);
if (topWorlds.length === 1) {
const { name, feeling, line } = worlds[topWorlds[0]];
console.log(`你最需要的是${name}东哥。你现在需要的是${feeling}。`);
console.log(line);
return;
}
const names = topWorlds.map((slug) => worlds[slug].name);
console.log(`${names.join("、")}同分。不用只选一个，这几条线换着看：`);
topWorlds.forEach((slug) => {
console.log(worlds[slug].line);
});
}单独的 return; 后面不跟任何值，作用只是“到此结束，离开函数”。
写 validateAnswers：先检查，再计分
写函数 validateAnswers(questions, answers)：答案没问题时返回空字符串 ""；有问题时返回一句中文说明。要检查两件事：答案个数和题目数是否一致；每个答案是否是 0 到“选项数减 1”之间的整数。
提示：个数不一致就直接 return 说明。然后用 for 循环逐个检查，遇到第一个无效的就 return。判断整数用 Number.isInteger(值)，它对 2 返回 true，对 1.5 和 NaN 都返回 false。全部通过后 return 空字符串。空字符串是假值，调用的地方可以直接写 if (error)。
learn/js/quiz-cli.js
// 4. 检查答案：没问题返回空字符串，有问题返回说明
function validateAnswers(questions, answers) {
if (answers.length !== questions.length) {
return `答案有 ${answers.length} 个，题目有 ${questions.length} 道，数量对不上`;
}
for (let i = 0; i < answers.length; i++) {
const answer = answers[i];
const optionCount = questions[i].options.length;
if (!Number.isInteger(answer) || answer < 0 || answer >= optionCount) {
return `第 ${i + 1} 题的答案 ${answer} 不在 0 到 ${optionCount - 1} 之间`;
}
}
return "";
}为什么要单独检查“是不是整数”？如果答案是 NaN，NaN < 0 和 NaN >= 3 都是 false，只靠范围判断会让它蒙混过关。
写主流程，运行完整程序
删掉前面所有临时加的 console.log，在文件最后写主流程：先检查答案，有问题就输出“出错了：”加说明；没问题就依次计分、找最高分、输出结果。然后运行：
node quiz-cli.js提示：主流程只是按顺序调用前面四个函数，大约 8 行。
函数的排列顺序：先数据，再函数，最后主流程。
learn/js/quiz-cli.js
// 你最需要哪个东哥：文字版测试
// 运行方法：node quiz-cli.js
// 1. 三个世界的信息：以 slug 为属性名的查找表
const worlds = {
gentleman: {
name: "绅士",
feeling: "安全感",
line: "去看绅士线：球房里安静的一小时，只有球声和呼吸。",
},
street: {
name: "街头",
feeling: "心动",
line: "去看街头线：后座视角，路线就是内容。摔了，冲镜头笑。",
},
thai: {
name: "泰风",
feeling: "被保护感",
line: "去看泰风线：打完拳，安静地收手带，给拳馆的狗添水。",
},
};
// 2. 六道题：每个选项对应一个世界
const questions = [
{
text: "周末下午，你更想去哪里？",
options: [
{ text: "安静的球房", world: "gentleman" },
{ text: "滑板公园", world: "street" },
{ text: "拳馆", world: "thai" },
],
},
{
text: "哪个瞬间最容易打动你？",
options: [
{ text: "他瞄准时专注的那几秒", world: "gentleman" },
{ text: "他摔了之后冲镜头笑", world: "street" },
{ text: "他训练完安静地收拾手带", world: "thai" },
],
},
{
text: "一起出门，你希望他穿什么？",
options: [
{ text: "马甲、衬衫、皮鞋", world: "gentleman" },
{ text: "Baggy 裤配 Vans", world: "street" },
{ text: "泰拳短裤和 T 恤", world: "thai" },
],
},
{
text: "你最近最缺的是什么？",
options: [
{ text: "一点确定感", world: "gentleman" },
{ text: "一点新鲜感", world: "street" },
{ text: "一点有人撑腰的感觉", world: "thai" },
],
},
{
text: "背景音你选哪一种？",
options: [
{ text: "只有击球声", world: "gentleman" },
{ text: "鼓点和说唱", world: "street" },
{ text: "拳套的击打声", world: "thai" },
],
},
{
text: "如果一起旅行，你想去哪？",
options: [
{ text: "有老球房的城市", world: "gentleman" },
{ text: "街头文化最热闹的街区", world: "street" },
{ text: "曼谷的拳馆", world: "thai" },
],
},
];
// 3. 一组固定的答案：每个数字是所选选项的下标
const answers = [2, 1, 2, 0, 2, 1];
// 4. 检查答案：没问题返回空字符串，有问题返回说明
function validateAnswers(questions, answers) {
if (answers.length !== questions.length) {
return `答案有 ${answers.length} 个，题目有 ${questions.length} 道，数量对不上`;
}
for (let i = 0; i < answers.length; i++) {
const answer = answers[i];
const optionCount = questions[i].options.length;
if (!Number.isInteger(answer) || answer < 0 || answer >= optionCount) {
return `第 ${i + 1} 题的答案 ${answer} 不在 0 到 ${optionCount - 1} 之间`;
}
}
return "";
}
// 5. 计分：返回每个世界的得分
function calcScores(questions, answers) {
const scores = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((answerIndex, questionIndex) => {
const option = questions[questionIndex].options[answerIndex];
scores[option.world]++;
});
return scores;
}
// 6. 找出得分最高的世界：同分时全部返回
function findTopWorlds(scores) {
const maxScore = Math.max(...Object.values(scores));
return Object.keys(scores).filter((slug) => scores[slug] === maxScore);
}
// 7. 输出结果
function printResult(topWorlds, scores) {
console.log(`得分：绅士 ${scores.gentleman}，街头 ${scores.street}，泰风 ${scores.thai}`);
if (topWorlds.length === 1) {
const { name, feeling, line } = worlds[topWorlds[0]];
console.log(`你最需要的是${name}东哥。你现在需要的是${feeling}。`);
console.log(line);
return;
}
const names = topWorlds.map((slug) => worlds[slug].name);
console.log(`${names.join("、")}同分。不用只选一个，这几条线换着看：`);
topWorlds.forEach((slug) => {
console.log(worlds[slug].line);
});
}
// 8. 主流程
const error = validateAnswers(questions, answers);
if (error) {
console.log(`出错了：${error}`);
} else {
const scores = calcScores(questions, answers);
const topWorlds = findTopWorlds(scores);
printResult(topWorlds, scores);
}运行结果：
得分：绅士 1，街头 2，泰风 3
你最需要的是泰风东哥。你现在需要的是被保护感。
去看泰风线：打完拳，安静地收手带，给拳馆的狗添水。node quiz-cli.js，输出和参考答案一样的三行。测试同分
把 answers 改成 [0, 1, 0, 1, 1, 0] 再运行，这组答案让绅士和街头各得 3 分。再改成 [0, 1, 2, 0, 1, 2]，三个世界各 2 分。
提示：运行前先自己算一遍每个世界的得分，再看程序的输出对不对得上。
第一组答案的输出：
得分：绅士 3，街头 3，泰风 0
绅士、街头同分。不用只选一个，这几条线换着看：
去看绅士线：球房里安静的一小时，只有球声和呼吸。
去看街头线：后座视角，路线就是内容。摔了，冲镜头笑。第二组答案的输出：
得分：绅士 2，街头 2，泰风 2
绅士、街头、泰风同分。不用只选一个，这几条线换着看：
去看绅士线：球房里安静的一小时，只有球声和呼吸。
去看街头线：后座视角，路线就是内容。摔了，冲镜头笑。
去看泰风线：打完拳，安静地收手带，给拳馆的狗添水。测试错误的答案
依次把 answers 改成下面两组，确认程序给出清楚的中文提示，而不是崩溃：[0, 1, 5, 1, 1, 0]（第 3 题选了不存在的选项）和 [0, 1, 2, 1, 1]（少了一个答案）。测完把 answers 改回 [2, 1, 2, 0, 2, 1]。
第一组的输出：
出错了：第 3 题的答案 5 不在 0 到 2 之间第二组的输出：
出错了：答案有 5 个，题目有 6 道，数量对不上想看看没有检查时会怎样，可以临时把主流程改成直接计分（跳过 validateAnswers），用第一组答案运行，你会看到上午第 7 节那种 TypeError。看完改回来。
选做：从命令行传入答案，然后提交
每次改答案都要改代码太麻烦。让程序支持这样运行：node quiz-cli.js 0 1 0 1 1 0，命令后面的数字就是答案；什么都不写时，仍然用固定的那组答案。
提示：Node 提供了一个数组 process.argv，里面是这次运行命令的各个部分，第 0 项是 node 程序的路径，第 1 项是 quiz-cli.js 的路径，从第 2 项开始才是你在后面写的内容，而且都是字符串。数组的 slice(2) 方法返回“从下标 2 到最后”组成的新数组。用 map 和 Number 把字符串转成数字。
只需要把第 3 步的那一行答案换成下面三行：
learn/js/quiz-cli.js
// 3. 答案：命令行里给了就用命令行的，没给就用固定的一组
const input = process.argv.slice(2);
const answers = input.length > 0 ? input.map(Number) : [2, 1, 2, 0, 2, 1];node quiz-cli.js
node quiz-cli.js 0 1 0 1 1 0
node quiz-cli.js 0 1 a 1 1 0第一行和原来一样，输出泰风；第二行输出绅士、街头同分；第三行输出“出错了：第 3 题的答案 NaN 不在 0 到 2 之间”，因为 Number("a") 是 NaN，被 validateAnswers 拦住了。
最后提交今天的成果：
cd ~/code/learn
git add js
git commit -m "DAY 18：文字版测试 quiz-cli.js"
git pushgentlemen，选项写 gentleman。这时 scores["gentleman"] 是 undefined，undefined 加 1 得到 NaN。Math.max 忘了加 ...，直接传了数组会得到 NaN；传了一个空数组展开后什么都没有，会得到 -Infinity。const answers 的上面。数据要写在最前面，主流程写在文件最后。两个世界同分时，你的计分函数会怎样？应该怎样？
如果找最高分时用 > 逐个比较、只记一个世界，同分时后面的世界不比前面的“大”，不会替换，所以返回的是在记分板对象里排在前面的那个。结果取决于写代码时属性的顺序，和访客的回答无关，这是一个隐藏的 bug。
应该事先明确规定同分怎么处理。我的做法是把所有并列的世界都找出来：先用 Math.max(...Object.values(scores)) 算出最高分，再用 filter 留下所有等于最高分的世界，输出时告诉访客“这几个世界同分，换着看”。其他合理的规定也可以，比如用某一道关键题决胜负，但必须是有意识的规定。
scores[option.world]++ 为什么不能写成 scores.option.world++？
option.world 是一个变量表达式，里面存的是 "thai" 这样的世界名，要用它的值当属性名，必须用方括号。scores.option.world 的意思是“先找 scores 里一个叫 option 的属性，再找它的 world 属性”，scores 里没有 option，得到 undefined，再读 world 就会报 TypeError。
运行时报 TypeError: Cannot read properties of undefined (reading 'world')，可能是什么原因？你会怎么查？
意思是在 undefined 上读 world 属性，也就是 option 是 undefined。最可能是某个答案的下标超出了选项范围（比如 5），或者答案个数比题目多，questions[questionIndex] 本身就是 undefined。
查法：看报错里的文件名和行号，找到出错的那一行；在它前面用 console.log 打印 questionIndex、answerIndex 和取到的值；找到原因后，用 validateAnswers 在计分前把无效答案拦住。
querySelector 和 querySelectorAll 选中链接主页上的任意元素。textContent、classList、style 修改元素的文字和样式。createElement 和 append 把 looks 数组变成页面上的穿搭卡片，没有数据时显示空状态。textContent 和 innerHTML 的区别，以及用户输入为什么不能直接放进 innerHTML。过去六天，你写的 JavaScript 都只在控制台和终端里输出文字。DAY 16 的 looks 数组、DAY 17 的平台对象、DAY 18 的计分函数，访客都看不到。今天要把这些数据真正放到链接主页上，让它变成访客能看到的卡片。
打个比方。你写的 index.html 是一张装修设计图。浏览器拿到设计图后，会照着它搭出一个真实的样板间。设计图是文件，躺在硬盘上不会变；样板间搭好以后，你可以随时进去挪沙发、换灯泡、加一面墙。这个样板间就是 DOM（Document Object Model，文档对象模型）。
DOM 是浏览器根据 HTML 在内存里建出来的一棵“树”。每个标签变成树上的一个节点，也叫元素。父标签是树枝，子标签是从树枝上长出来的小枝。JavaScript 不能直接改你的 HTML 文件，但它可以改这棵树，改完浏览器马上重新画页面。你的链接主页，在浏览器眼里大致是这样一棵树：
document
└── html
├── head
│ ├── title
│ └── script (script.js)
└── body
├── header
│ ├── img（头像）
│ ├── h1（三岁的东哥）
│ └── p（一句话介绍）
└── main
├── nav（四个平台按钮）
└── section#looks（今天要加的穿搭区）最顶上的 document 是整棵树的入口，JavaScript 里所有 DOM 操作都从它开始。打开 Chrome 的开发者工具（快捷键 Cmd + Option + I），Elements 面板里看到的就是这棵树。注意：它显示的是“当前的样板间”，不是硬盘上的设计图。等会儿你用 JavaScript 加了卡片，Elements 里能看到卡片，但 index.html 文件里不会多出一行。
名字里的 Object（对象）也值得多看一眼。DOM 树上的每个节点，都是 DAY 17 学过的那种 JavaScript 对象：它有属性，比如 textContent（里面的文字）、className（它的 class）；也有方法，比如 append()（往里面放东西）、remove()（把自己删掉）。你已经会读写对象的属性、调用对象的方法，所以操作 DOM 并不是全新的语法，只是换了一批属性名和方法名要记。在控制台里输入 console.dir(document.body)，能看到 body 这个对象身上的几百个属性，今天只需要认识其中七八个。
JavaScript 要改 DOM，前提是 DOM 已经搭好。浏览器读 HTML 是从上往下一行一行读的，读到 <script> 标签时，默认会停下来先下载并运行这个脚本，运行完再接着往下读。如果脚本写在 <head> 里，那时候 <body> 里的元素还没被搭出来，脚本去找 #look-list 就会扑空。
解决办法是给 script 标签加 defer 属性。defer 的意思是“延后”：浏览器会一边读 HTML 一边在后台下载脚本，等整棵 DOM 树搭完了再运行它。
links/index.html
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>三岁的东哥</title>
<link rel="stylesheet" href="style.css">
<script src="script.js" defer></script>
</head>逐行看：前面几行是你 DAY 05 以来一直有的内容。最后一行 <script src="script.js" defer></script> 引入同一个文件夹里的 script.js。src 是脚本的路径，defer 不需要写值，写上就生效。script 标签必须有结束标签 </script>，不能写成自闭合。
</body> 前面的写法，那也是为了等 DOM 搭好。两种都能用，这门课统一用 head 里加 defer，所有引用集中在一处，好找。要改样板间里的某张沙发，先得找到它。DOM 提供了两个最常用的“找东西”方法，它们接收的参数就是你 DAY 06 学过的 CSS 选择器，写法一模一样。
const title = document.querySelector("h1");
const lookList = document.querySelector("#look-list");
const firstButton = document.querySelector(".platform-btn");
const allButtons = document.querySelectorAll(".platform-btn");
console.log(title.textContent);
console.log(allButtons.length);
allButtons.forEach((button) => {
console.log(button.textContent);
});逐行解释：
document.querySelector("h1")：在整个页面里找第一个匹配 h1 的元素，返回这个元素本身。"#look-list"：井号表示按 id 找，和 CSS 里一样。一个页面里 id 不能重复，所以按 id 找最准。".platform-btn"：点表示按 class 找。页面上有四个平台按钮，querySelector 只返回第一个。querySelectorAll：返回所有匹配的元素，装在一个叫 NodeList 的“类数组”里。它有 length，也能用 DAY 16 学过的 forEach 遍历，但没有 map 和 filter。forEach 把每个按钮的文字打印出来，你会看到小红书、TikTok、Facebook、Instagram 依次出现。如果选择器什么都没找到，querySelector 会返回 null（空）。这时再去读它的属性就会报错：Cannot read properties of null。看到这句报错，第一反应就是检查选择器有没有拼错、元素是不是还没被搭出来。querySelectorAll 找不到时不会返回 null，而是返回一个长度为 0 的空列表。
DAY 06 学过的组合选择器在这里也都能用。document.querySelector(".looks h2") 找穿搭区里的标题；document.querySelectorAll("nav a") 找导航里的所有链接。你还可能在旧教程里看到 document.getElementById("look-list")，它只能按 id 找，参数不带井号。效果一样，但 querySelector 一种写法通吃所有选择器，这门课统一用它。
找到元素后，最常做的三件事是改文字、加减 class、改单个样式。
const title = document.querySelector("h1");
title.textContent = "三岁的东哥 · 今天练拳";
title.classList.add("highlight");
title.classList.remove("highlight");
title.classList.toggle("highlight");
title.style.color = "#b5171f";
title.style.letterSpacing = "2px";textContent：元素里的纯文字。读它能拿到文字，给它赋值会把元素里原来的内容全部换掉。classList.add("highlight")：给元素加上 highlight 这个 class。remove 是去掉，toggle 是“有就去掉，没有就加上”，像电灯开关。style.color：直接改元素的行内样式。注意 CSS 里带连字符的属性名，在 JavaScript 里要改成驼峰写法：letter-spacing 写成 letterSpacing，background-color 写成 backgroundColor。值永远是字符串，单位不能省，要写 "2px" 而不是 2。那什么时候用 classList，什么时候用 style？原则是：样式写在 CSS 里，JavaScript 只负责开关 class。比如“高亮”的样子在 style.css 里写好，JS 只管加上或去掉 highlight。这样样式都集中在 CSS 文件，以后改颜色不用翻 JS。只有当样式的值来自数据、没法提前写进 CSS 时，才用 style。今天的穿搭卡片就是这种情况：每套穿搭的主色存在数组里，六套六个颜色，所以用 style.backgroundColor 设置。
还有一种很有用的写法叫 data 属性。HTML 允许你给任何元素加以 data- 开头的自定义属性，用来存一点跟这个元素有关的数据，浏览器不会拿它做任何事，专门留给 JavaScript 读。
// 假设 HTML 里有：<article class="look-card" data-world="street">
const card = document.querySelector(".look-card");
console.log(card.dataset.world); // "street"
card.dataset.world = "thai"; // 改成泰风在 JavaScript 里通过 元素.dataset.名字 读写，名字就是 data- 后面那一截。今天的卡片会给自己标上 data-world，明天做风格切换按钮时，按钮也会用 data-world 记住自己代表哪个世界。
改已有的元素还不够。looks 数组里有几套穿搭，页面上就该有几张卡片，而 HTML 里事先并不知道有几套。所以要用 JavaScript “现造”元素，再放进页面。造一个元素分三步：造出来、装修好、挂上去。
const card = document.createElement("article");
card.className = "look-card";
const title = document.createElement("h3");
title.textContent = "马甲三件套";
card.append(title);
document.querySelector("#look-list").append(card);document.createElement("article")：造一个新的 <article> 元素。刚造出来时它只存在于内存里，还没进页面，屏幕上看不到。card.className = "look-card"：设置它的 class。className 会整体覆盖；如果只想加一个 class，用上一节的 classList.add。h3，用 textContent 填上穿搭名称。card.append(title)：把标题放进卡片里，成为卡片的子元素。append 会把东西加在最后面，一次可以放多个：card.append(a, b, c)。#look-list。这一步之后，卡片才真正出现在屏幕上。删除更简单：先选中，再调用 remove()。
const firstCard = document.querySelector(".look-card");
firstCard.remove();如果要一次清空某个容器里的所有子元素，可以写 lookList.innerHTML = ""。给 innerHTML 赋一个空字符串，意思是“里面什么都不要了”。这是 innerHTML 少数可以放心用的场景，因为空字符串里没有任何内容，下一节你会明白为什么要强调这一点。
你可能会想：一张卡片要写十几行 createElement，太啰嗦了，能不能直接拼一段 HTML 字符串塞进去？技术上可以，很多教程也这么写。但拼字符串有两个隐患：一是穿搭名字里如果出现尖括号之类的字符，会把结构搞乱；二是一旦数据来自用户，就会埋下下一节要讲的安全问题。createElement 的写法虽然长，每一步都清清楚楚，而且文字全部走 textContent，天生安全。等学了 React，这些啰嗦的步骤会由 React 替你完成，而且它默认就是安全的写法。
元素还有一个属性叫 innerHTML，看起来和 textContent 很像，区别在于：textContent 把你给它的字符串当成文字原样显示；innerHTML 会把字符串当成 HTML 代码交给浏览器解析，里面的标签会变成真的元素。
const box = document.querySelector("#look-count");
box.textContent = "<strong>街头</strong>";
// 页面显示：<strong>街头</strong>（尖括号原样出现）
box.innerHTML = "<strong>街头</strong>";
// 页面显示：加粗的“街头”两个字看起来 innerHTML 更方便，能直接写标签。问题出在内容不是你写的的时候。DAY 21 你会做“给东哥留言”表单，以后留言还会存进数据库、显示在页面上。假设有人在留言框里输入的不是一句话，而是这样一段：
const userInput = '<img src="x" onerror="alert(1)">';
box.innerHTML = userInput; // 危险
box.textContent = userInput; // 安全用 innerHTML 放进去，浏览器会真的造一个图片元素。图片地址 x 不存在，加载失败，于是触发 onerror 里的代码。这里只是弹一个框，但攻击者完全可以换成“读取访客的登录信息发到他的服务器”。更糟的是，如果这条留言被存下来，每个打开页面的人都会中招。这类攻击叫 XSS（跨站脚本攻击），DAY 45 会专门讲。
用 textContent 放进去，浏览器只把它当成一串普通文字显示出来，尖括号就是尖括号，什么代码都不会执行。
textContent。innerHTML 只用来清空容器，或者放你自己写死、确定安全的内容。今天的卡片全部用 createElement 加 textContent 来造，就是在养成这个习惯。把上面几节组合起来，就是今天下午要做的事：写一个函数，输入一套穿搭的数据，输出一张造好的卡片；再写一个函数，输入一个穿搭数组，把所有卡片放进页面。这种“数据进去，界面出来”的函数，通常叫 render（渲染）函数。
looks 数组 ──> renderLooks(looks) ──> 对每一项调用 createLookCard(look) ──> 卡片放进 #look-list这样拆有两个好处。第一，改卡片长什么样，只改 createLookCard 一处。第二，将来数据变了，比如只想显示街头的穿搭，只要把筛选后的数组再交给 renderLooks 重新画一遍，不用手动去删哪张、加哪张。这个思路很重要：DAY 27 开始学的 React，核心就是“数据变了，界面自动重画”，今天你是在手工体验它的前身。
写 render 函数时，建议守住一条分工：数据只存在数组里，页面只是数组的一张“照片”。想加一套穿搭，就往 looks 数组里加一项，再调用一次 renderLooks；不要跑到页面上手动 append 一张卡片，而数组里却没有这一项。一旦页面和数组对不上，就会出现“页面上有 7 张卡，数量却写着共 6 套”这种怪事。下午第 9 步你会亲手制造一次这种不一致，记住那个感觉。
明天学事件：让页面对访客的点击和输入做出反应。今天造好的 renderLooks 明天会直接用上。
打开项目，确认 script.js 已经引入
在终端进入链接主页项目，用 VS Code 打开：
cd ~/code/links
code .打开 index.html，看 <head> 里有没有 <script src="script.js" defer></script>。没有就照上午第 2 节加上；如果你之前把 script 写在了 </body> 前面，把它挪到 head 里并加上 defer。确认文件夹里有 script.js，没有就新建一个空的。
在 Finder 里双击 index.html，用 Chrome 打开页面。
在控制台里热身
按 Cmd + Option + J 打开控制台，逐行输入并回车：
document.querySelector("h1").textContent
document.querySelector("h1").textContent = "三岁的东哥 · 今天练拳"
document.querySelectorAll("a").length
document.querySelector("h1").style.color = "#b5171f"第一行读出标题文字，第二行改掉它，第三行数一数页面上有几个链接，第四行把标题变成泰风红。然后按 Cmd + R 刷新。
在 index.html 里加穿搭区的空容器
在 <main> 里、“三个世界”区块的后面，加上下面这段。卡片本身不写在 HTML 里，只留一个空的 div 等 JavaScript 来填。
links/index.html
<section class="looks" id="looks">
<h2>最近的穿搭</h2>
<p class="look-count" id="look-count"></p>
<div class="look-list" id="look-list"></div>
</section>look-count 用来显示“共几套”，look-list 是放卡片的容器。两个 id 等会儿都要在 JS 里用到，拼写要一致。
把 looks 数组搬进 script.js
DAY 16 你在 ~/code/learn/js/ 里写过 looks 数组。今天在 links/script.js 里写一份正式的，同时准备一个“世界英文名到中文名”的对照表。先自己敲，再对照：
links/script.js
// ===== 1. 穿搭卡片（DAY 19） =====
const worldNames = {
gentleman: "绅士",
street: "街头",
thai: "泰风",
};
const looks = [
{ name: "马甲三件套", world: "gentleman", color: "#2f3e46" },
{ name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80" },
{ name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ name: "泰拳短裤训练装", world: "thai", color: "#b5171f" },
{ name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];
const lookList = document.querySelector("#look-list");
const lookCount = document.querySelector("#look-count");worldNames 是一个对象，用 worldNames[look.world] 就能把 "street" 换成 "街头"，这是 DAY 17 学的方括号读法。最后两行提前选好两个容器，后面的函数都会用到。穿搭名字和颜色可以换成你自己真实的衣服。
写 createLookCard：一套数据变一张卡片
接着在 script.js 里写。这个函数接收一个穿搭对象，返回一张造好的卡片，但它自己不负责把卡片放进页面。
links/script.js
function createLookCard(look) {
const card = document.createElement("article");
card.className = "look-card";
card.dataset.world = look.world;
const swatch = document.createElement("div");
swatch.className = "look-swatch";
swatch.style.backgroundColor = look.color;
const title = document.createElement("h3");
title.textContent = look.name;
const tag = document.createElement("p");
tag.className = "look-world";
tag.textContent = worldNames[look.world];
card.append(swatch, title, tag);
return card;
}逐段看：造一个 article 当卡片外壳，用 dataset.world 给它标上所属的世界（在 Elements 面板里会显示成 data-world="street"）；造一个色块 div，背景色来自数据，所以用 style；造标题和世界标签，文字全部用 textContent 填；最后用一次 append 把三样东西按顺序放进卡片，return 交出去。如果忘了写 return，调用这个函数只会得到 undefined，这就是 DAY 15 验收题说的那种错误。
写 renderLooks：把整个数组画到页面上
links/script.js
function renderLooks(list) {
lookList.innerHTML = "";
if (list.length === 0) {
const empty = document.createElement("p");
empty.className = "look-empty";
empty.textContent = "这里还没有穿搭，过两天再来看看。";
lookList.append(empty);
}
list.forEach((look) => {
lookList.append(createLookCard(look));
});
lookCount.textContent = `共 ${list.length} 套`;
}
renderLooks(looks);第一行先清空容器，保证重复调用时不会越画越多。接着处理空数组：没有数据就放一句空状态提示。然后用 forEach 给每套穿搭造一张卡片并放进容器。最后用 DAY 13 学过的模板字符串（反引号加 ${}）更新数量。文件最后一行真正调用它。
保存，回到浏览器刷新。
给卡片加样式
打开 style.css，在最后加上：
links/style.css
/* ===== 穿搭卡片（DAY 19） ===== */
.look-list {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 12px;
}
@media (min-width: 768px) {
.look-list {
grid-template-columns: repeat(3, 1fr);
}
}
.look-card {
border: 1px solid #ddd;
border-radius: 12px;
overflow: hidden;
background: #fff;
}
.look-swatch {
height: 80px;
}
.look-card h3 {
margin: 12px 12px 4px;
font-size: 1rem;
}
.look-world {
margin: 0 12px 12px;
font-size: 0.875rem;
color: #666;
}
.look-empty {
grid-column: 1 / -1;
color: #666;
}这里用的是 DAY 08 的 Grid：手机两列，768px 以上三列。repeat(2, 1fr) 等于写两次 1fr。overflow: hidden 让色块跟着卡片的圆角被裁掉。grid-column: 1 / -1 让空状态文字横跨所有列，不会挤在第一格里。颜色可以换成你 DAY 09 定的 CSS 变量。
在 Elements 面板里看 JS 造出来的元素
打开开发者工具的 Elements 面板，展开 #look-list，你能看到 6 个 article，每个色块上有 style="background-color: ..."。再打开 VS Code 里的 index.html，#look-list 依然是空的。把这两个画面对照着看一遍，这就是“设计图”和“样板间”的区别。
测试空状态和删除
在控制台里输入：
renderLooks([])
renderLooks(looks)
document.querySelector(".look-card").remove()第一行传一个空数组，看空状态；第二行恢复；第三行删掉第一张卡片。
亲手做一次 innerHTML 实验
还是在控制台，逐行输入：
const box = document.querySelector("#look-count")
box.textContent = "<strong>街头</strong>"
box.innerHTML = "<strong>街头</strong>"
box.innerHTML = '<img src="x" onerror="alert(1)">'
box.textContent = '<img src="x" onerror="alert(1)">'提交到 Git
cd ~/code/links
git add index.html style.css script.js
git commit -m "用 JavaScript 从 looks 数组生成穿搭卡片"
git pushDAY 12 你已经把 links 连上了 Vercel，push 之后线上网址会自动更新。等一两分钟，在手机上打开你的链接主页看看卡片。
querySelector 没找到元素，返回了 null。检查三处：选择器是否拼错（#look-list 的井号别漏）；HTML 里的 id 是否和 JS 里一致；script 标签有没有加 defer。script.js 是不是 404，通常是 src 路径写错了。style.background-color，JavaScript 里要写 style.backgroundColor；或者颜色值漏了井号。另外 .look-swatch 必须有高度，否则色块高度为 0 看不见。renderLooks(looks) 被调用了两次且函数开头没有清空容器，要么 index.html 里引入了两次 script.js。textContent 和 innerHTML 有什么区别？为什么把用户输入直接放进 innerHTML 很危险？
textContent 把字符串当成纯文字显示，里面的尖括号原样出现，不会被解析；innerHTML 把字符串当成 HTML 代码交给浏览器解析，里面的标签会变成真的元素。用户输入可能是一段精心构造的 HTML，比如一个加载失败的图片带上 onerror 代码，放进 innerHTML 后这段代码会在访客的浏览器里执行，可以偷数据、改页面，这就是 XSS。如果这条输入被存下来显示给所有人，每个访客都会中招。所以用户输入一律用 textContent。
链接主页上有 4 个 class 为 platform-btn 的按钮。document.querySelector(".platform-btn") 和 document.querySelectorAll(".platform-btn") 分别拿到什么？怎样把 4 个按钮的文字都打印出来？
querySelector 只拿到第一个匹配的元素，也就是小红书按钮；querySelectorAll 拿到全部 4 个，装在一个 NodeList 里。打印文字：document.querySelectorAll(".platform-btn").forEach((button) => console.log(button.textContent));
如果把 head 里 script 标签的 defer 去掉，今天的卡片还会出现吗？为什么？
不会。浏览器读到 head 里的 script 就会立即运行它，这时 body 还没被读到，#look-list 和 #look-count 还不存在，querySelector 返回 null，后面调用 append 或设置 textContent 时就会报错。defer 让脚本等整个 DOM 搭好再运行。
addEventListener 让按钮、输入框对访客的操作做出反应。event.target 和输入框的值，并说清 target 和 currentTarget 的区别。localStorage 记住访客的选择。input 事件做一个边输入边筛选的穿搭搜索框。昨天的 script.js 是“一口气跑完”的：页面打开，代码从上到下运行一遍，卡片画好，结束。但真实的网页要一直“待命”：访客点了按钮才换风格，输入了文字才开始搜索。今天学的事件，就是让代码学会等待。
打个比方。事件监听像给家门装门铃。你不需要一整天站在门口盯着有没有人来，只要装好门铃，再交代一句“门铃响了就去开门”，然后该干嘛干嘛。浏览器就是那个一直听着门铃的人：访客点击、输入、按键、提交表单，都会让浏览器“响一次铃”，这个铃声就叫一个事件（event）。你提前交代好的“响了之后做什么”，是一个函数，叫事件处理函数。
常见的事件有这些，今天先用前两个：
| 事件名 | 什么时候触发 | 链接主页上的例子 |
|---|---|---|
click | 点击（手机上是轻点） | 点“街头”按钮换风格 |
input | 输入框的内容每变一次 | 搜索框里每打一个字就筛选一次 |
change | 内容改完并确认后（比如下拉框选定、输入框失去焦点） | 明天的留言表单里“最喜欢哪个世界”下拉框 |
submit | 表单被提交 | 明天的“给东哥留言”表单 |
keydown | 键盘上某个键被按下 | 按 Esc 关闭弹窗（以后会用到） |
给元素装监听器只有一种推荐写法：
const title = document.querySelector("h1");
title.addEventListener("click", () => {
console.log("有人点了标题");
});逐段看：title 是要监听的元素；addEventListener 意思是“添加事件监听器”；第一个参数 "click" 是事件名，是字符串，不带 on；第二个参数是一个函数，事件发生时浏览器会替你调用它。这里用的是 DAY 15 学过的箭头函数。
第二个参数也可以传一个提前写好的函数名：
function sayHi() {
console.log("有人点了标题");
}
title.addEventListener("click", sayHi); // 正确：把函数交给浏览器，等点击时再调用
title.addEventListener("click", sayHi()); // 错误：这里立刻就调用了 sayHi这两行只差一对括号，意思完全不同。不带括号的 sayHi 是“这个函数本身”，相当于把门铃响后要做的事写在纸上交给浏览器；带括号的 sayHi() 是“现在就执行它”，页面一打开就执行了一次，交给浏览器的是它的返回值 undefined，之后再怎么点都没反应。这是今天最常见的错误，写完监听器先看一眼括号。
同一个元素可以装好几个监听器，它们会按添加的顺序依次运行，互不覆盖。比如标题上既装了一个“打印日志”的监听器，又装了一个“变色”的监听器，点一下两件事都会发生。如果以后想拆掉某个监听器，可以用 removeEventListener("click", sayHi)，但前提是装的时候传的是有名字的函数；箭头函数没有名字，拆不掉。链接主页上的监听器装上就一直用，今天不需要拆。
<button onclick="..."> 这种把代码写在 HTML 属性里的写法。它能用，但会把 HTML 和 JavaScript 搅在一起，一个元素也只能挂一个处理函数。这门课统一用 addEventListener。浏览器调用你的处理函数时，会顺手传进来一个参数，里面装着这次事件的详细信息，叫事件对象。习惯上把这个参数命名为 event。
const lookSearch = document.querySelector("#look-search");
lookSearch.addEventListener("input", (event) => {
console.log(event.type); // "input"
console.log(event.target); // 触发事件的那个元素，也就是搜索框
console.log(event.target.value); // 搜索框里现在的文字
});event.type：事件名，这里是 "input"。event.target：事件真正发生在哪个元素上。在输入框里打字，target 就是输入框。event.target.value：输入框、文本框、下拉框都有 value 属性，表示当前的值，永远是字符串。注意是 value 不是 textContent，输入框里的文字不算它的“子内容”。事件对象里还有一个容易混的属性叫 event.currentTarget，表示“监听器装在哪个元素上”。在上面这个例子里，监听器就装在搜索框上，所以 target 和 currentTarget 是同一个元素。等讲完下一节的冒泡，你就会遇到两者不同的情况。
不同的事件，事件对象里装的信息也不同。键盘事件里有 event.key，告诉你按的是哪个键：
document.addEventListener("keydown", (event) => {
if (event.key === "Escape") {
console.log("访客按了 Esc");
}
});这里监听器装在 document 上，意思是整个页面任何地方按键都算。event.key 的值是按键的名字，字母键就是那个字母，比如 "a"，Esc 键是 "Escape"，回车是 "Enter"。遇到不认识的事件，最快的学习方法是在处理函数里写一行 console.log(event)，然后在控制台里展开它，看看里面都有哪些属性。
今天要给链接主页加一组风格切换按钮，它们的 HTML 结构是这样的：
<body>
<header>
<div class="theme-switcher">
<button type="button" data-world="gentleman">绅士</button>
<button type="button" data-world="street">街头</button>
<button type="button" data-world="thai">泰风</button>
</div>
</header>
</body>当访客点“街头”按钮时，他同时也点在了 .theme-switcher 上、header 上、body 上，因为按钮就在它们里面。浏览器处理这次点击的方式是：先在按钮上触发 click，然后自动往上一层一层传，在 .theme-switcher 上再触发一次，接着是 header、body、html，一直传到 document。这个过程叫事件冒泡，像水底冒出的气泡一路浮到水面。
用一段代码亲眼看看：
document.querySelector(".theme-switcher button").addEventListener("click", () => {
console.log("1. 按钮收到了点击");
});
document.querySelector(".theme-switcher").addEventListener("click", () => {
console.log("2. 切换区收到了点击");
});
document.body.addEventListener("click", () => {
console.log("3. body 收到了点击");
});点“绅士”按钮，控制台依次打印 1、2、3。点切换区里按钮之间的空隙，只打印 2、3，因为点击发生在切换区上，从那里开始往上冒。点页面别的地方，只打印 3。
冒泡过程中，event.target 始终是最初被点的那个元素（比如“绅士”按钮），而 event.currentTarget 是“此刻正在处理事件的那一层”，也就是监听器所在的元素。在第 2 个监听器里，target 是按钮，currentTarget 是切换区。
event.stopPropagation() 可以让冒泡停在当前这一层，不再往上传。新手几乎用不到它，乱用反而会让上层的功能失灵。知道有这回事就够了。冒泡听起来像个副作用，其实非常好用。先看最直接的写法：给三个按钮各装一个监听器。
document.querySelectorAll(".theme-switcher button").forEach((button) => {
button.addEventListener("click", () => {
console.log("访客选了：", button.dataset.world);
});
});这样写能用，页面上实际装了三个监听器。另一种写法是利用冒泡，只在三个按钮共同的父元素 .theme-switcher 上装一个，然后看 event.target 判断点的是哪个按钮。这种写法叫事件委托：像公司前台替各部门接电话，来电先到前台，前台看一眼是找谁的，再转过去。
const themeSwitcher = document.querySelector(".theme-switcher");
themeSwitcher.addEventListener("click", (event) => {
const button = event.target.closest("button");
if (!button) {
return;
}
console.log("访客选了：", button.dataset.world);
});event.target.closest("button")：从被点的元素开始，包括它自己，一层层往上找，找到的第一个 button 就返回。为什么不直接用 event.target？因为按钮里以后可能会放图标或者 <span> 小字，点到小字时 target 是那个 span 而不是按钮，closest 能帮你找回按钮。if (!button) { return; } 的意思是“没点到按钮就什么都不做，直接结束”。button.dataset.world 读出按钮上 data-world 的值，这是昨天学的 data 属性。事件委托有两个好处。第一，按钮再多也只需要一个监听器。第二，也是更重要的：它对“后来才出现的元素”同样有效。昨天的穿搭卡片是 JavaScript 动态造出来的，每次 renderLooks 都会整批换掉；如果给每张卡片单独装监听器，重画一次就得重装一次。把监听器装在不会被换掉的父容器 #look-list 上，就一劳永逸。
风格切换做好后会有个问题：访客选了街头风，一刷新又回到默认。因为 JavaScript 里的变量都在内存里，页面一刷新全部清零。要让选择“留下来”，需要把它存到一个刷新也不会丢的地方。
浏览器给每个网站都准备了一个小抽屉，叫 localStorage（本地存储）。它按“键和值”存东西，像贴了标签的收纳盒：标签是键，盒子里放的是值。
localStorage.setItem("dongge-theme", "street"); // 存：标签 dongge-theme，内容 street
localStorage.getItem("dongge-theme"); // 取："street"
localStorage.getItem("不存在的键"); // 取不到：null
localStorage.removeItem("dongge-theme"); // 删掉这一格
localStorage.setItem("visit-count", 3);
localStorage.getItem("visit-count"); // "3"，注意变成了字符串关于这个抽屉，有五件事要记住：
"3"。存对象要先转成 JSON 字符串，明天会用到。这里说的“同一个网站”，准确的叫法是源（origin），由三部分组成：协议（http 或 https）、域名、端口。三者完全一样才算同一个源，才共用一个抽屉。DAY 22 你会第一次用到本地服务器，网址会从 file:///... 变成 http://127.0.0.1:5500 这样的形式，那也是一个新的源，抽屉又是空的。每次抽屉“莫名其妙”变空，先看看网址是不是变了。
localStorage 的容量大约是每个源 5MB，存几个设置、几十条留言绰绰有余，但它不适合当数据库用：数据只在访客自己的浏览器里，东哥在自己的电脑上根本看不到访客存了什么。真正要让东哥看到的数据，比如粉丝提问，DAY 43 会存进服务器上的数据库。
现在把前面所有知识点连成一条线。你 DAY 09 已经给三个世界各写了一套 CSS 变量，页面长成哪种风格，取决于 body 上挂的是哪个 class。所以风格切换本质上只做一件事：换掉 body 上的 class。完整流程是：
页面打开
└─ 读 localStorage 里的 dongge-theme
├─ 是 gentleman / street / thai 之一 ──> 应用这个风格
└─ 是 null 或者别的怪值 ──────────────> 应用默认的绅士风格
访客点了某个风格按钮（事件委托）
└─ 读按钮的 data-world
├─ 换掉 body 上的 class，并高亮当前按钮
└─ 把选择存进 localStorage这里有个值得学的设计：“应用某个风格”这件事在两个地方都要做（页面打开时、点击按钮时），所以把它写成一个函数 applyTheme(world)，两处都调用它。同样的代码只写一遍，改的时候也只改一处。这和昨天把卡片写成 createLookCard 是同一个思路。
明天学表单：在“给东哥留言”表单上用 submit 事件，读取访客填写的内容并做校验。今天学的事件对象和 localStorage，明天都会继续用。
核对三套风格的 class 名
打开 ~/code/links/style.css，找到 DAY 09 写的三套颜色变量。今天的 JavaScript 会用 theme-gentleman、theme-street、theme-thai 这三个 class 名，挂在 body 上。如果你当时起的名字不一样，统一改成这三个。结构大致是这样，颜色用你自己定的：
links/style.css
body.theme-gentleman {
--bg: #f4f1ea;
--text: #1f2a2e;
--accent: #2f4f4f;
}
body.theme-street {
--bg: #121212;
--text: #f5f5f5;
--accent: #ff5a1f;
}
body.theme-thai {
--bg: #fff7ec;
--text: #2b1a12;
--accent: #b5171f;
}
body {
background: var(--bg);
color: var(--text);
transition: background 0.3s, color 0.3s;
}最后一段让页面背景和文字使用变量，transition 让切换时颜色平滑过渡。如果 index.html 的 body 上还写着 DAY 09 手动加的 class，先保留，等会儿 JS 会接管它。
在 header 里加切换按钮
打开 index.html，在 header 里一句话介绍的下面加：
links/index.html
<div class="theme-switcher">
<button type="button" data-world="gentleman">绅士</button>
<button type="button" data-world="street">街头</button>
<button type="button" data-world="thai">泰风</button>
</div>用 button 而不是 div，是 DAY 05 的验收题：button 天生能被键盘选中、能被读屏软件识别。type="button" 表示它是普通按钮，不是提交按钮。再在 style.css 最后加上按钮样式：
links/style.css
/* ===== 风格切换（DAY 20） ===== */
.theme-switcher {
display: flex;
justify-content: center;
gap: 8px;
margin: 16px 0;
}
.theme-switcher button {
padding: 8px 16px;
border: 1px solid var(--accent);
border-radius: 999px;
background: transparent;
color: var(--text);
font: inherit;
cursor: pointer;
}
.theme-switcher button.is-active {
background: var(--accent);
color: var(--bg);
}在控制台里观察冒泡
打开控制台，把上午第 4 节那三段监听代码整段粘贴进去回车，然后分别点“绅士”按钮、按钮之间的空隙、页面空白处，对照打印结果。
写 applyTheme 函数
在 script.js 里 DAY 19 的代码下面接着写：
links/script.js
// ===== 2. 风格切换（DAY 20） =====
const THEME_KEY = "dongge-theme";
const worlds = ["gentleman", "street", "thai"];
const themeSwitcher = document.querySelector(".theme-switcher");
const themeButtons = document.querySelectorAll(".theme-switcher button");
function applyTheme(world) {
document.body.classList.remove("theme-gentleman", "theme-street", "theme-thai");
document.body.classList.add(`theme-${world}`);
themeButtons.forEach((button) => {
button.classList.toggle("is-active", button.dataset.world === world);
});
}THEME_KEY 是存进 localStorage 用的标签名，全大写表示“这是一个不会变的常量”，写成常量可以避免存和取时拼错。classList.remove 一次可以去掉多个 class，先把三种都去掉，再加上要的那一种。classList.toggle 这里传了第二个参数：它为 true 时加上 class，为 false 时去掉。button.dataset.world === world 只有当前世界对应的按钮是 true，于是只有它被高亮。
保存后在控制台输入 applyTheme("street")、applyTheme("thai") 试试。
用事件委托接上点击
links/script.js
themeSwitcher.addEventListener("click", (event) => {
const button = event.target.closest("button");
if (!button) {
return;
}
const world = button.dataset.world;
applyTheme(world);
localStorage.setItem(THEME_KEY, world);
});一个监听器管三个按钮。点到按钮就读它的 data-world，应用风格，再存进抽屉。
页面打开时读出上次的选择
links/script.js
const savedTheme = localStorage.getItem(THEME_KEY);
if (worlds.includes(savedTheme)) {
applyTheme(savedTheme);
} else {
applyTheme("gentleman");
}worlds.includes(savedTheme) 检查读出来的值是不是三个世界之一。第一次来的访客读到 null，或者有人在开发者工具里把值改成了乱七八糟的东西，都会走 else，用默认的绅士风格。这就是上午说的“读出来的值要检查”。
选一个街头风，然后刷新页面。
打开抽屉看一眼
在开发者工具顶部找到 Application 面板（如果被折叠，点 >> 展开），左侧展开 Local storage，点下面的网址，能看到一行：键 dongge-theme，值 street。双击值改成 thai，刷新页面；再改成 abc，刷新页面。
加一个穿搭搜索框
在 index.html 的穿搭区里，#look-count 上面加：
links/index.html
<label for="look-search">搜穿搭</label>
<input type="search" id="look-search" placeholder="比如：马甲、Vans">然后把 DAY 19 的 renderLooks 改成可以接收自定义的空状态文字。函数参数可以写默认值：调用时不传第二个参数，就用等号后面的文字。
links/script.js
function renderLooks(list, emptyText = "这里还没有穿搭，过两天再来看看。") {
lookList.innerHTML = "";
if (list.length === 0) {
const empty = document.createElement("p");
empty.className = "look-empty";
empty.textContent = emptyText;
lookList.append(empty);
}
list.forEach((look) => {
lookList.append(createLookCard(look));
});
lookCount.textContent = `共 ${list.length} 套`;
}最后在风格切换代码的下面加上搜索：
links/script.js
// ===== 3. 穿搭搜索（DAY 20） =====
const lookSearch = document.querySelector("#look-search");
lookSearch.addEventListener("input", (event) => {
const keyword = event.target.value.trim().toLowerCase();
const result = looks.filter((look) => look.name.toLowerCase().includes(keyword));
renderLooks(result, "没找到这套穿搭，换个词试试。");
});trim() 去掉首尾空格，toLowerCase() 把英文转成小写，这样搜 vans 也能找到 Vans。关键词为空字符串时，includes("") 永远是 true，所有穿搭都会显示，正好是清空搜索框时想要的效果。筛选用的是 DAY 16 的 filter，画页面用的是昨天的 renderLooks。
用键盘测试一遍
点一下页面空白处，然后反复按 Tab 键，焦点会依次跳到平台按钮、风格按钮、搜索框。焦点停在“泰风”按钮上时按 Enter 或空格。
提交并在手机上验证
cd ~/code/links
git add index.html style.css script.js
git commit -m "加上风格切换、记住选择和穿搭搜索"
git push等 Vercel 部署完成，在手机上打开线上网址，切换一次风格，关掉浏览器再打开。
addEventListener("click", applyTheme("street"))。带括号就是立刻调用。第二个参数必须是函数本身，或者一个箭头函数。data-world（连字符），JS 里是不是 dataset.world；再检查 CSS 里的 class 名是否正好是 theme-street 这种格式。可以在监听器第一行加 console.log(event.target) 看看到底点到了什么。THEME_KEY 常量的原因。另外 Safari 和 Chrome 的无痕窗口关闭后会清空抽屉，测试请用普通窗口。toLowerCase()。用你自己的页面举例，解释事件冒泡。
我的链接主页上，“街头”按钮在 .theme-switcher 里，切换区在 header 里，header 在 body 里。我点“街头”按钮时，click 事件先在按钮上触发，然后自动往上传：切换区、header、body、html、document 依次都会收到这次点击。这就是冒泡。我的风格切换正是利用了它：监听器只装在切换区上，三个按钮的点击都冒泡上来，再用 event.target.closest("button") 找出点的是哪个按钮。
在切换区的监听器里，访客点了“泰风”按钮。此时 event.target 和 event.currentTarget 分别是什么？如果按钮里有个 <span>，访客正好点在 span 上，会有什么不同？
target 是“泰风”按钮，也就是真正被点的元素；currentTarget 是切换区 .theme-switcher，也就是监听器所在的元素。如果点在按钮里的 span 上，target 就变成了 span，这时直接读 event.target.dataset.world 会得到 undefined。所以要用 closest("button") 从 span 往上找回按钮。
执行 localStorage.setItem("visit-count", 3) 后再 getItem，得到什么？为什么页面打开时读出风格后，要先用 worlds.includes() 检查一下？
得到字符串 "3"，localStorage 只能存字符串。读出风格后要检查，是因为读到的可能不是有效值：第一次来的访客读到 null；访客可以在开发者工具里把值改成任何东西；以后改版删掉某个风格，老访客的抽屉里还存着旧值。只有确认是三个世界之一才应用，否则用默认的绅士风格。
preventDefault 阻止页面刷新。submit 事件里读取输入框、文本框、下拉框的值，并用 trim 去掉多余空格。JSON.stringify 和 JSON.parse 把一条条留言存进 localStorage，再在开发者工具里查看。DAY 05 你给链接主页写了一个“给东哥留言”的表单，当时说好“先不提交”。今天让它真正工作起来。第一步，要先了解表单天生的行为。
HTML 表单诞生的年代，网页还没有 JavaScript。那时候表单的工作方式很直接：访客点提交，浏览器把所有填写的内容打包，发到表单 action 属性指定的地址，然后整个页面跳转去显示服务器返回的新页面。如果没写 action，就发给当前这个网址。这个行为今天依然保留着，叫表单的默认行为。
你现在的表单没有 action，也没有 JavaScript 接管，点“发送”会发生什么？浏览器会把内容拼到网址后面，重新打开当前页面。网址会变成类似这样：
file:///Users/dong/code/links/index.html?nickname=小林&world=street&content=想看你练BMX问号后面就是表单数据，每一项是 name=值，用 & 连起来。这里的 nickname、world、content，来自每个输入框的 name 属性。页面刷新后，你填的东西全没了，也没有任何“发送成功”的提示。对一个单页的链接主页来说，这完全不是想要的效果。
现代网页的做法是：让 JavaScript 截住这次提交，自己读取数据、自己检查、自己决定接下来做什么，页面不跳转。下面几节就是在学怎么“截住”。
表单被提交时会触发 submit 事件。你昨天学会了装监听器，今天要多学一个事件对象上的方法：event.preventDefault()，意思是“阻止默认行为”。
打个比方：快递员上门取件，默认流程是拿了包裹就走。你说“等一下，我先检查一遍地址写没写对”，快递员就停下来等你。preventDefault 就是那句“等一下”：浏览器原本要打包数据、跳转页面，调用它之后，这些都不做了，控制权交给你的代码。
const messageForm = document.querySelector("#message-form");
messageForm.addEventListener("submit", (event) => {
event.preventDefault();
console.log("表单提交被我接管了");
});form 上，监听 submit，不是装在“发送”按钮上监听 click。event.preventDefault() 写在处理函数的第一行。放在最前面，是为了万一后面的代码出错中断了，页面也不会跳走，你还能在控制台看到报错。为什么要监听表单的 submit，而不是按钮的 click？因为提交表单的方式不止一种：点提交按钮是一种，在输入框里按回车也是一种，读屏软件还有自己的提交方式。不管哪种，最后都会触发表单的 submit 事件。只监听按钮的 click，访客按回车时你的代码就被绕过了，页面照样刷新。
type="submit"。所以表单里那些不是用来提交的按钮（比如今天的“再写一条”），一定要写 type="button"，否则点它也会提交表单。截住提交以后，下一步是读出访客填了什么。昨天你已经见过 value：输入框、多行文本框、下拉框，当前的值都在它们的 value 属性里。
const nicknameInput = document.querySelector("#nickname");
const worldSelect = document.querySelector("#world");
const contentInput = document.querySelector("#content");
const nickname = nicknameInput.value.trim();
const world = worldSelect.value;
const content = contentInput.value.trim();nicknameInput.value：称呼输入框里的文字。worldSelect.value：下拉框当前选中的那个 option 的 value 属性，比如 "street"，而不是显示给访客看的中文。这就是为什么 option 要同时写 value 和文字：value 给程序用，文字给人看。trim()：去掉字符串开头和结尾的空格、换行。访客可能只敲了几个空格就点发送，不 trim 的话，" " 看起来不是空字符串，会混过校验。三个值读出来都是字符串，哪怕访客输入的是数字。字符串的 length 属性就是字数，一个汉字算 1。
还有一种读法值得认识一下，叫 FormData。它按照每个输入的 name 属性，一次把整张表单的数据收集起来：
const formData = new FormData(messageForm);
formData.get("nickname"); // 称呼输入框的值
formData.get("world"); // 下拉框的值
formData.get("content"); // 留言框的值这就是为什么每个输入框都要写 name：默认提交时浏览器靠它拼网址，FormData 也靠它认人。今天的表单只有三项，用 value 一个个读更直观，下午的代码就用这种。但请记住 FormData 这个名字，DAY 43 用 Next.js 的 Server Actions 接收表单时，服务器那边拿到的正是一个 FormData，用法和这里一模一样。
校验，就是提交前检查内容是否符合要求。它有两个目的：一是及时告诉访客哪里不对，不让他白填；二是挡住明显无效的数据，比如一条空留言。
HTML 本身就提供了一些校验属性，你在 DAY 05 可能已经用过：
<textarea id="content" name="content" maxlength="200" required></textarea>required 表示必填，maxlength="200" 表示最多输入 200 个字符，打到第 200 个字就再也打不进去。不写任何 JavaScript，点提交时浏览器就会弹出“请填写此字段”的小气泡。
那为什么还要自己写？有三个原因。第一，浏览器自带的气泡样式和文字你改不了，每个浏览器长得还不一样。第二，它的规则很有限，比如“全是空格也算没填”它就判断不了，required 会认为几个空格也是填了。第三，这些属性写在 HTML 里，任何人在开发者工具里删掉 maxlength 就绕过了，下午你会亲手试一次。
所以常见的做法是：给 form 加上 novalidate 属性，关掉浏览器自带的气泡，改用 JavaScript 统一校验、统一显示提示；同时保留 required 和 maxlength，因为 required 能让读屏软件告诉视障访客“这是必填项”，maxlength 能在正常使用时直接限制输入。
自己写校验时，建议把规则单独写成一个函数：输入要检查的值，输出错误提示；没有错误就返回空字符串。
const MAX_CONTENT = 200;
const MAX_NICKNAME = 20;
function validateMessage(nickname, content) {
if (content === "") {
return "留言还是空的，写一句再发吧。";
}
if (content.length > MAX_CONTENT) {
return `留言最多 ${MAX_CONTENT} 个字，现在是 ${content.length} 个。`;
}
if (nickname.length > MAX_NICKNAME) {
return `称呼最多 ${MAX_NICKNAME} 个字。`;
}
return "";
}逐行看：两个常量把“200”“20”这样的数字起了名字，以后想改上限只改一处，提示文字也会跟着变。函数从上到下依次检查，遇到第一个问题就 return 对应的提示，后面的检查不再执行。三关都过了，最后返回空字符串，表示“没有问题”。提示文字要说清是哪里错、怎么改，比如“现在是 213 个”，比一句“输入有误”有用得多。
单独写成函数还有一个好处：可以在控制台里直接测试它，validateMessage("", "")、validateMessage("小林", "想看你打斯诺克")，不用每次都去页面上填表。DAY 51 学单元测试时，你会发现这种“输入进去、结果出来”的函数最容易测。
什么时候校验也有讲究。一种是提交时才查，另一种是边输入边查。边输入边查听起来更及时，但访客刚打了一个字就看到红字“太短了”，体验反而很糟。比较稳妥的组合是：提交时做完整校验并显示错误；输入过程中只显示中性的信息，比如字数统计，不报错。今天就按这个组合来做。
校验出了问题，要让访客看到；提交成功了，也要让访客知道。反馈有几个细节值得讲究。
错误提示放在表单里固定的位置。在“发送”按钮上方留一个空的 <p id="form-error">，有错误时用 textContent 填进去，没错误时清空。给它加上 aria-live="polite"，读屏软件就会在文字变化时把它念出来。
边输入边显示字数。用昨天学的 input 事件，访客每打一个字，就更新一次“38 / 200”。这样他不用等到提交才知道写多了。
function updateCharCount() {
charCount.textContent = `${contentInput.value.length} / ${MAX_CONTENT}`;
}
contentInput.addEventListener("input", updateCharCount);注意第二个参数是 updateCharCount，不带括号，这是昨天讲过的要点。
成功后换成感谢语。提交成功时，把表单藏起来，把一段感谢语显示出来。HTML 有个现成的属性叫 hidden，元素带着它就不显示。JavaScript 里用 元素.hidden = true 藏起来，元素.hidden = false 显示出来。再配合 form.reset()，把表单里所有输入恢复成初始状态。
感谢语的文案也守住“说事情不说情话”：告诉访客接下来会发生什么，比如“收到了。东哥每周日晚上统一看留言。”具体、可信，不需要额外的煽情。
留言要存下来。真正的做法是发给服务器存进数据库，那是 DAY 43 的事。今天先存在访客自己浏览器的 localStorage 里，练习数据的整理和存取。
一条留言有好几项信息，适合用对象表示；很多条留言，适合用数组装起来。问题是昨天说过，localStorage 只能存字符串。这就需要 JSON：一种把对象和数组写成字符串的标准格式。JavaScript 内置了两个转换工具：
const message = { nickname: "小林", world: "street", content: "想看你练 BMX" };
const text = JSON.stringify(message);
// '{"nickname":"小林","world":"street","content":"想看你练 BMX"}'
const back = JSON.parse(text);
// 又变回对象，back.nickname 是 "小林"JSON.stringify 把对象“压扁”成字符串，好放进抽屉；JSON.parse 把字符串“展开”回对象，好在代码里使用。明天读 data.json 文件时会系统地讲 JSON 的写法规则。
存一条新留言的完整过程是“取出来、加进去、放回去”：
const MESSAGES_KEY = "dongge-messages";
function saveMessage(message) {
const saved = JSON.parse(localStorage.getItem(MESSAGES_KEY) || "[]");
saved.push(message);
localStorage.setItem(MESSAGES_KEY, JSON.stringify(saved));
}getItem 返回 null。null || "[]" 的结果是 "[]"：|| 左边是“空”的值时，就取右边的值。于是 parse 得到一个空数组。push 加上新的一条，再整个转成字符串放回去。访客点“发送”或按回车
└─ 表单触发 submit
└─ preventDefault()：页面不跳转
└─ 读取 称呼 / 世界 / 留言，trim 去空格
└─ validateMessage 校验
├─ 有问题 ──> 在 #form-error 显示原因，结束
└─ 没问题 ──> saveMessage 存进 localStorage
└─ 清空表单，藏起表单，显示感谢语这条流程以后会反复出现。DAY 30 用 React 重写这个表单，DAY 43 让它真正发到服务器，DAY 44 在服务器上用 Zod 校验，骨架都是这一张图，只是每一格的实现越来越专业。
明天学异步和 fetch：把平台链接和介绍文字从 script.js 里搬到一个单独的 data.json 文件里，让页面去读取它。
对照更新表单的 HTML
打开 ~/code/links/index.html，找到 DAY 05 写的留言表单，改成下面这样。重点核对 id 和 name，今天的 JS 全靠它们找元素。
links/index.html
<section class="message" id="message">
<h2>给东哥留言</h2>
<form id="message-form" novalidate>
<label for="nickname">怎么称呼你（选填）</label>
<input type="text" id="nickname" name="nickname" maxlength="20">
<label for="world">你最常看哪个世界</label>
<select id="world" name="world">
<option value="gentleman">绅士：斯诺克和马甲</option>
<option value="street">街头：BMX 和滑板</option>
<option value="thai">泰风：泰拳</option>
</select>
<label for="content">想对东哥说的话</label>
<textarea id="content" name="content" rows="4" maxlength="200" required
placeholder="比如：想看你打一局完整的斯诺克"></textarea>
<p class="char-count" id="char-count">0 / 200</p>
<p class="form-error" id="form-error" aria-live="polite"></p>
<button type="submit">发送</button>
</form>
<div class="form-thanks" id="form-thanks" hidden>
<p>收到了。东哥每周日晚上统一看留言。</p>
<button type="button" id="write-again">再写一条</button>
</div>
</section>每个输入都有 label，for 和输入的 id 一致。感谢区一开始带着 hidden，是藏起来的。
先看一次表单的默认行为
这时 script.js 里还没有表单相关的代码。刷新页面，填一个称呼、一句留言，点“发送”。
?nickname=...&world=...&content=...。这就是上午第 1 节说的默认行为。再做一个小实验：在 Elements 面板里选中 form 标签，双击 novalidate 把它删掉，然后什么都不填直接点“发送”，会看到浏览器自带的“请填写此字段”气泡。刷新页面恢复。
加上表单相关的样式
links/style.css
/* ===== 留言表单（DAY 21） ===== */
[hidden] {
display: none !important;
}
#message-form {
display: flex;
flex-direction: column;
gap: 8px;
}
.char-count {
margin: 0;
font-size: 0.875rem;
text-align: right;
color: #888;
}
.form-error {
margin: 0;
min-height: 1.5em;
color: #c1121f;
}
.form-thanks {
padding: 16px;
border: 1px solid var(--accent);
border-radius: 12px;
}第一条规则很关键：浏览器对 hidden 的处理本质上是一条 display: none，优先级很低。你的表单写了 display: flex，会把它盖过去，结果设置了 hidden 却藏不住。!important 让这条规则压过其他所有写法，保证 hidden 一定生效。.form-error 的 min-height 给错误提示预留一行高度，出现提示时下面的按钮不会突然往下跳。
选好元素，做字数统计
在 script.js 最后接着写：
links/script.js
// ===== 4. 留言表单（DAY 21） =====
const MAX_CONTENT = 200;
const MAX_NICKNAME = 20;
const MESSAGES_KEY = "dongge-messages";
const messageForm = document.querySelector("#message-form");
const nicknameInput = document.querySelector("#nickname");
const worldSelect = document.querySelector("#world");
const contentInput = document.querySelector("#content");
const charCount = document.querySelector("#char-count");
const formError = document.querySelector("#form-error");
const formThanks = document.querySelector("#form-thanks");
const writeAgainButton = document.querySelector("#write-again");
function updateCharCount() {
charCount.textContent = `${contentInput.value.length} / ${MAX_CONTENT}`;
}
contentInput.addEventListener("input", updateCharCount);写校验函数，并在控制台里测试
把上午第 4 节的 validateMessage 函数加进 script.js（常量已经在上一步写过，不要重复写）。保存刷新，在控制台里逐行测试：
validateMessage("", "")
validateMessage("小林", "想看你打一局完整的斯诺克")
validateMessage("一个非常非常非常非常非常非常长的称呼啊", "你好")
validateMessage("", "好".repeat(201))"好".repeat(201) 会生成 201 个“好”字，用来测试超长的情况。
写 saveMessage
把上午第 6 节的 saveMessage 函数加进 script.js，同样不要重复写 MESSAGES_KEY。
接管 submit：校验、保存、显示感谢
links/script.js
messageForm.addEventListener("submit", (event) => {
event.preventDefault();
const nickname = nicknameInput.value.trim();
const world = worldSelect.value;
const content = contentInput.value.trim();
const error = validateMessage(nickname, content);
if (error !== "") {
formError.textContent = error;
return;
}
formError.textContent = "";
saveMessage({
nickname: nickname || "匿名",
world,
content,
createdAt: new Date().toISOString(),
});
messageForm.reset();
updateCharCount();
messageForm.hidden = true;
formThanks.hidden = false;
});逐段看：第一行阻止跳转；接着现读三个值；校验不通过就显示原因并 return 结束；通过了先清掉旧的错误提示，再保存。nickname || "匿名"：没填称呼时 nickname 是空字符串，于是存成“匿名”。world, 是 world: world, 的简写，键名和变量名相同时可以只写一次，这是 DAY 17 对象那天见过的写法。new Date().toISOString() 把当前时间变成 2026-10-17T12:30:00.000Z 这样的标准格式字符串，方便存储。最后清空表单、把字数归零、换成感谢语。
让“再写一条”按钮工作
links/script.js
writeAgainButton.addEventListener("click", () => {
formThanks.hidden = true;
messageForm.hidden = false;
contentInput.focus();
});focus() 让光标直接落在留言框里，访客可以马上开始写。
在开发者工具里查看存下来的留言
再提交两三条不同的留言，然后打开 Application 面板，Local storage 里找到 dongge-messages。它的值是一整段 JSON 字符串。再在控制台里输入：
JSON.parse(localStorage.getItem("dongge-messages"))亲手绕过 HTML 的长度限制
在 Elements 面板里选中 textarea，删掉它的 maxlength 属性。然后在控制台执行 copy("好".repeat(230))，copy 是 Chrome 控制台自带的小工具，会把 230 个“好”字复制到剪贴板。在留言框里按 Cmd + V 粘贴，点发送。
提交并上线
cd ~/code/links
git add index.html style.css script.js
git commit -m "留言表单：前端校验、字数统计、存入 localStorage"
git push"submit"、event.preventDefault() 有没有写、处理函数有没有接收 event 参数。如果 script.js 前面某处报错，后面的代码都不会运行，先看控制台有没有红字。display: flex 之类盖过了 hidden。加上第 3 步的 [hidden] { display: none !important; }。.trim()。dongge-messages 的值不是合法的 JSON，通常是你在 Application 面板里手动改坏了。在面板里右键删掉这一行就好。明天会学用 try/catch 优雅地处理这类错误。type="button"，默认就是提交按钮。按第 1 步的结构，它应该在 form 外面、在感谢区里，并写上 type="button"。提交表单时为什么通常要调用 preventDefault？
表单的默认行为是把数据打包发给 action 指定的地址（没写就是当前网址），然后整个页面跳转或刷新。这样访客填的内容会丢失，你的代码也没机会校验和给出提示。调用 event.preventDefault() 可以阻止这个默认行为，让 JavaScript 接管：自己读取数据、校验、保存，再决定显示错误还是显示感谢语，页面不跳转。
为什么要监听 form 的 submit 事件，而不是“发送”按钮的 click 事件？
提交表单的方式不止点按钮一种，在输入框里按回车、读屏软件的提交操作，都会提交表单。它们最终都会触发 form 的 submit 事件，但不一定触发按钮的 click。只监听 click，访客按回车时校验就被绕过，页面照样刷新。
textarea 上已经写了 maxlength="200"，为什么 JS 里还要检查长度？有了前端校验，是不是就能防住恶意提交了？
HTML 属性写在页面上，任何人都能在开发者工具里删掉，下午第 10 步就演示了这一点，所以 JS 要再检查一次。但 JS 校验同样运行在访客的浏览器里，懂技术的人可以改掉它，或者干脆跳过页面直接给服务器发数据。前端校验的作用是改善体验、及时提示，不是安全措施。真正的防线要在服务器上再校验一遍，DAY 44 会讲。
fetch 加 async/await 读取 data.json，用读到的数据生成平台按钮。try/catch 和 response.ok 处理“文件不存在”“格式写错”“网络断开”等情况，给访客显示友好的提示。npx serve 启动本地服务器。前三天，你写的每一行代码都是“马上完成”的：选中元素、改文字、存 localStorage，一眨眼就做完了。今天要做的事不一样：去读一个文件。读文件，尤其是从网络上读，需要时间，可能几十毫秒，网不好时可能好几秒。
想象你点了一份外卖。有两种等法。第一种：下完单就站在门口一动不动，直到外卖送到，中间什么都不干。这叫同步，一件事做完才做下一件。第二种：下完单该洗澡洗澡、该剪视频剪视频，外卖到了门铃一响再去拿。这叫异步，先发起一件要花时间的事，不干等，结果来了再处理。
浏览器里的 JavaScript 只有一个“人”在干活（术语叫单线程）。如果它用第一种方式等网络，等待期间页面就完全卡死：按钮点不动、页面滚不动。所以凡是要花时间的操作，比如网络请求、定时器，JavaScript 都用异步的方式处理。
console.log("1. 下单");
setTimeout(() => {
console.log("3. 外卖到了");
}, 2000);
console.log("2. 先去洗澡");把这段粘贴进控制台运行，打印顺序是 1、2，两秒后才是 3。setTimeout 的意思是“过一段时间再执行这个函数”，第二个参数是毫秒，2000 就是 2 秒。关键在于：JavaScript 不会停在 setTimeout 那里等两秒，它交代完就继续往下走，先打印了 2。这就是异步。
上面传给 setTimeout 的那个箭头函数，叫回调函数（callback）：你把一个函数交给别人，说“等你那边好了，回头调用它”。就像下单时留了电话，外卖到了骑手打给你。昨天的 addEventListener 其实也是回调：点击发生时，浏览器回头调用你给的函数。
回调很直观，但要做一连串有先后顺序的异步操作时，就会一层套一层：
setTimeout(() => {
console.log("外卖到了");
setTimeout(() => {
console.log("吃完了");
setTimeout(() => {
console.log("垃圾扔了");
}, 1000);
}, 1000);
}, 1000);每多一步，代码就往右缩进一层，还要在每一层处理可能的错误，很快就变得难读难改。这种样子有个外号叫“回调地狱”。为了解决它，JavaScript 引入了 Promise。
下单以后，外卖平台会给你一张订单。订单不是外卖本身，而是一个“承诺”：这份外卖将来会有一个结果。订单有三种状态：
一张订单只会从 pending 变成另外两种之一，而且变了就不会再变。Promise（承诺）就是 JavaScript 里的这张订单。一个要花时间的函数，不直接返回结果，而是马上返回一个 Promise；结果出来后，Promise 的状态随之改变。下面这段代码模拟一次点外卖，你不需要会写 new Promise，能看懂就行，以后你用的 fetch 会自动帮你生成 Promise：
function orderTakeout(dish) {
return new Promise((resolve, reject) => {
setTimeout(() => {
if (dish === "") {
reject(new Error("没选菜，商家拒单"));
} else {
resolve(`${dish}送到了`);
}
}, 2000);
});
}
orderTakeout("泰式炒河粉")
.then((result) => console.log(result))
.catch((error) => console.log(error.message));orderTakeout 调用后立刻返回一个 Promise，也就是订单。reject，订单变成失败；否则调用 resolve，订单变成成功，结果是“泰式炒河粉送到了”。.then(...)：订单成功时做什么，括号里的函数会收到结果。.catch(...)：订单失败时做什么，括号里的函数会收到错误。error.message 是错误的说明文字。把 "泰式炒河粉" 换成 "" 再运行一次，两秒后会打印“没选菜，商家拒单”。
then 和 catch 比回调好读多了，但还有更顺手的写法：async/await。它让异步代码读起来就像普通的从上往下执行的代码。
async function dinner() {
console.log("下单");
try {
const result = await orderTakeout("泰式炒河粉");
console.log(result);
console.log("开吃");
} catch (error) {
console.log("出问题了：", error.message);
}
}
dinner();
console.log("等外卖的时候，先去洗个澡");async function：在函数前面加 async，表示这是一个异步函数，里面才能用 await。await orderTakeout(...)：await 的意思是“等这张订单出结果”。订单成功，await 就得到结果，赋值给 result；订单失败，await 会抛出错误，直接跳到 catch。try { ... } catch (error) { ... }：把可能出错的代码放进 try，一旦其中某一行出错，就不再执行 try 里剩下的代码，跳进 catch 处理。这样页面不会因为一个错误整个停摆。运行后打印顺序是：下单、等外卖的时候先去洗个澡、（两秒后）泰式炒河粉送到了、开吃。注意第二行：await 只会让 dinner 这个函数自己停下来等，不会让整个页面停下来。dinner 在 await 处暂停，外面的代码继续跑。这就是“下了单去洗澡，外卖到了再接着吃”。
用一句话总结今天的外卖比喻：Promise 是订单，代表一个将来才有的结果；await 是“等这张订单出结果再往下走”，但只有这一件事在等，你的其他事照常进行；try/catch 是“万一商家拒单，我有备用方案”。
await 只能写在 async 函数里面。在普通 script.js 的最外层直接写 await 会报错：await is only valid in async functions。浏览器控制台是个例外，它允许你直接写 await，方便测试。昨天你用 JSON.stringify 把留言变成字符串存起来。今天要单独写一个 .json 文件，所以要把 JSON 的写法规则搞清楚。
JSON（JavaScript Object Notation）长得几乎和 JavaScript 的对象、数组一样，但它是一种独立的数据格式，几乎所有编程语言都能读写它。你以后写的服务器、调用的 Claude API，来回传的数据基本都是 JSON。正因为要让所有语言都认得，它的规则比 JavaScript 严格：
| 规则 | JavaScript 对象里可以 | JSON 里必须 |
|---|---|---|
| 键名 | { name: "小红书" } | { "name": "小红书" }，键名必须用双引号 |
| 字符串 | 单引号、双引号、反引号都行 | 只能用双引号 |
| 最后一项后面的逗号 | 可以留 | 不能留，多一个逗号整个文件就读不出来 |
| 注释 | 可以写 // 注释 | 不能写任何注释 |
| 值的类型 | 什么都行，包括函数 | 只能是字符串、数字、true/false、null、数组、对象 |
VS Code 会检查 .json 文件的格式，写错的地方会标红波浪线，保存前看一眼右下角的“问题”数量是不是 0。
格式不对的 JSON 在解析时会直接报错，不会“尽量读一点”。昨天的坑里提到过：localStorage 里的留言被改坏后，JSON.parse 报了 Unexpected token。今天有了 try/catch，就可以把解析放进 try 里，出错时给一个备用值，而不是让整段脚本停掉。下午你会故意在 data.json 里多写一个逗号，看看 catch 怎么接住它。
fetch（取来）是浏览器内置的函数，用来发出网络请求。你在 DAY 03 学过一次网页访问的过程：浏览器发请求，服务器回响应，响应里有状态码。fetch 就是让你在 JavaScript 里亲手发一次请求。
async function loadProfile() {
const response = await fetch("data.json");
console.log(response.status); // 200 表示成功，404 表示没找到
console.log(response.ok); // 状态码在 200 到 299 之间时为 true
const data = await response.json();
console.log(data.name); // "三岁的东哥"
}fetch("data.json")：请求和当前页面同一个文件夹里的 data.json。它返回一个 Promise，所以要 await。response 是一个响应对象，像快递员递给你的包裹，此时你只看到了外包装：状态码 status 和是否成功 ok。response.json()：拆开包裹，把里面的 JSON 文字解析成 JavaScript 对象。拆包也需要时间，所以它也返回 Promise，也要 await。一个 fetch 通常要 await 两次，新手最常漏掉第二次。还有一个非常重要的细节：fetch 只有在网络彻底不通时才会失败，比如断网、服务器地址根本不存在。如果服务器正常回了话，只是说“404 没找到这个文件”，fetch 并不算失败，Promise 照样成功，你拿到一个 ok 为 false 的 response。所以你必须自己检查 response.ok，不 ok 就主动抛出一个错误：
if (!response.ok) {
throw new Error(`读取 data.json 失败，状态码 ${response.status}`);
}throw（抛出）的意思是“这里出问题了，别往下执行了”。在 try 里面 throw，程序会直接跳进 catch，和 await 遇到失败的效果一样。这样“断网”“文件不存在”“JSON 写错”三种问题，最后都进同一个 catch，统一给访客显示一句友好的提示。
到目前为止，你看链接主页都是在 Finder 里双击 index.html。这时候看一眼地址栏，网址是这样的：
file:///Users/dong/code/links/index.html开头是 file://，意思是浏览器直接从你的硬盘上读了这个文件，中间没有任何服务器。这种方式下，页面里的 fetch 去读 data.json 会失败，Chrome 控制台会报类似这样的错：
Fetch API cannot load file:///Users/dong/code/links/data.json. URL scheme "file" is not supported.原因有两层。第一层，fetch 是为 HTTP 请求设计的，它要的是 http:// 或 https:// 开头的地址，file:// 不在支持范围内。第二层是安全：设想你从网上下载了一个 html 文件，双击打开，如果它能用 fetch 随意读取你硬盘上的其他文件，它就能偷偷读你的文档、照片，再发到别人的服务器上。所以浏览器对 file:// 打开的页面管得非常严，不允许它这样读本地文件。Safari 的报错文字不一样，但原因相同。
解决办法是在自己电脑上运行一个本地服务器：一个小程序，像一个迷你版的 Vercel，专门负责接收浏览器的 HTTP 请求，再把 links 文件夹里的文件送回去。这时网址会变成：
http://127.0.0.1:5500/index.html127.0.0.1（也可以写成 localhost）是一个特殊地址，永远指向“你自己这台电脑”；5500 是端口号，可以理解成这台电脑上的门牌号，一台电脑能同时开很多个服务，靠端口区分。现在页面是通过 HTTP 送来的，fetch("data.json") 就是向同一个本地服务器再要一个文件，顺理成章。
你可能会问：前面三周双击打开都好好的，为什么现在才需要服务器？因为之前页面用到的 style.css、script.js、头像图片，都是 HTML 里用标签引用的，浏览器对这种引用比较宽松。fetch 是 JavaScript 主动去读文件，浏览器必须更警惕。而线上的 Vercel 本来就是一台 HTTPS 服务器，所以上线后从来不会有这个问题，本地服务器只是让你在自己电脑上模拟出和线上一样的环境。
这门课给你两种启动方式，任选一种：
npx serve：npx 是 DAY 01 装 Node.js 时一起装上的工具，可以临时下载并运行一个命令行小程序，用完不会留在你的项目里。serve 是 Vercel 出品的静态文件服务器，默认地址是 http://localhost:3000。明天学 npm 时你会知道它背后的原理。新建 data.json
在 ~/code/links 里新建 data.json，写入下面的内容。把链接换成你自己四个平台的主页地址，颜色可以按你的喜好调整。
links/data.json
{
"name": "三岁的东哥",
"intro": "在外面是绅士、拳手、潮男，在你面前三岁。",
"platforms": [
{ "name": "小红书", "url": "https://example.com/xiaohongshu", "color": "#ff2442" },
{ "name": "TikTok", "url": "https://example.com/tiktok", "color": "#111111" },
{ "name": "Facebook", "url": "https://example.com/facebook", "color": "#1877f2" },
{ "name": "Instagram", "url": "https://example.com/instagram", "color": "#e1306c" }
]
}对照上午的表格检查：键名全是双引号，最后一个平台后面没有逗号，没有注释。
example.com 只是占位地址。上线前一定换成你真实的主页链接，否则访客点进去是一个空白示例页。先在双击打开的页面里试一次 fetch
用 Finder 双击 index.html 打开，在控制台输入：
await fetch("data.json")file 不被支持，或者 Failed to fetch。你亲眼看到了上午第 7 节说的问题。启动本地服务器（两种方式任选一种）
方式 A：Live Server。在 VS Code 左侧点扩展图标（四个小方块），搜索 Live Server，认准作者 Ritwick Dey，点安装。装好后，确认 VS Code 打开的是 links 文件夹，点窗口右下角状态栏的 Go Live。浏览器会自动打开 http://127.0.0.1:5500/index.html。要停止时，点右下角显示 Port : 5500 的地方。
方式 B：npx serve。在终端运行：
cd ~/code/links
npx serve第一次运行会问 Need to install the following packages: serve ... Ok to proceed? (y)，输入 y 回车。看到 Serving! 和 Local: http://localhost:3000 后，在浏览器打开这个地址。这个终端窗口要一直开着，关掉或按 Ctrl + C 服务器就停了。
http:// 开头，页面正常显示。风格变回了绅士风，因为这是一个新的源，抽屉是空的。在控制台里拆一次包裹
在本地服务器打开的页面里，控制台逐行输入：
const response = await fetch("data.json")
response.status
response.ok
const data = await response.json()
data.platforms[0].name改 index.html：平台按钮交给 JavaScript 生成
给标题和介绍加上 id；把原来手写的四个平台 <a> 删掉，只留容器和一句“加载中”。容器上原来的 class 保留，DAY 07 写的 Flexbox 排版就不会丢。
links/index.html
<h1 id="site-name">三岁的东哥</h1>
<p id="intro">在外面是绅士、拳手、潮男，在你面前三岁。</p>
<!-- 下面这个 nav 的 class 用你原来写的，只加上 id -->
<nav class="platforms" id="platform-list" aria-label="东哥的平台">
<p class="loading">链接加载中…</p>
</nav>标题和介绍保留原来的文字：万一 data.json 读取失败，访客至少还能看到它们。
写 createPlatformButton 和 showLoadError
在 script.js 最后接着写：
links/script.js
// ===== 5. 从 data.json 读取资料（DAY 22） =====
const siteName = document.querySelector("#site-name");
const intro = document.querySelector("#intro");
const platformList = document.querySelector("#platform-list");
function createPlatformButton(platform) {
const link = document.createElement("a");
link.className = "platform-btn";
link.href = platform.url;
link.target = "_blank";
link.rel = "noopener";
link.textContent = platform.name;
link.style.borderColor = platform.color;
return link;
}
function showLoadError() {
platformList.innerHTML = "";
const message = document.createElement("p");
message.className = "load-error";
message.textContent = "平台链接暂时没加载出来。刷新一下试试，或者在小红书搜「三岁的东哥」。";
platformList.append(message);
}createPlatformButton 和 DAY 19 的 createLookCard 是同一个模式：一个平台对象进去，一个造好的链接出来。target="_blank" 在新标签页打开，rel="noopener" 防止新页面反过来控制你的页面。如果你 DAY 06 给按钮写的 class 不是 platform-btn，改成你的；如果按钮没有边框，borderColor 这行看不出效果，可以删掉。
写 loadProfile：读取、检查、显示
links/script.js
async function loadProfile() {
try {
const response = await fetch("data.json");
if (!response.ok) {
throw new Error(`读取 data.json 失败，状态码 ${response.status}`);
}
const data = await response.json();
siteName.textContent = data.name;
intro.textContent = data.intro;
platformList.innerHTML = "";
data.platforms.forEach((platform) => {
platformList.append(createPlatformButton(platform));
});
} catch (error) {
console.error(error);
showLoadError();
}
}
loadProfile();逐段看：fetch 并 await 响应；不 ok 就 throw；再 await 解析 JSON；用读到的数据填标题、介绍，清掉“加载中”，逐个生成平台按钮。任何一步出错都跳进 catch：console.error 把真实原因打印给你这个开发者看，showLoadError 给访客看一句人话。最后一行别忘了调用。
故意制造三种错误
依次做下面三个实验，每做完一个就改回来：
fetch("data.json") 改成 fetch("date.json")，拼错文件名。看看“加载中”长什么样
在 Network 面板里把网速改成 Slow 4G（或者 3G），刷新页面，注意平台区域。然后在 style.css 最后给两种提示加一点样式：
links/style.css
/* ===== 加载状态（DAY 22） ===== */
.loading,
.load-error {
margin: 0;
padding: 12px;
text-align: center;
font-size: 0.875rem;
color: #888;
}提交并上线
cd ~/code/links
git add data.json index.html style.css script.js
git commit -m "平台链接和介绍改为从 data.json 读取"
git pushVercel 本身就是一个 HTTPS 服务器，线上页面的 fetch 不会遇到 file:// 的问题。部署完成后在手机上打开检查。
npx serve 打开，地址栏变成 http:// 开头再试。loadProfile() 没有调用，或者 script.js 前面某处报错导致后面的代码没运行。看控制台有没有红字，从第一条报错开始修。if (!response.ok) 那段。404 时 fetch 不会失败，代码会把 404 页面当 JSON 去解析，或者拿到一个没有 platforms 的对象。用点外卖打比方，讲清 Promise 和 async/await。
点外卖时平台给你一张订单，订单就是 Promise：它不是外卖本身，而是“将来会有一个结果”的承诺，状态从进行中变成已送达（成功）或者被拒单（失败），变了就不再变。用 then 和 catch，相当于提前交代“送到了就开吃，拒单了就换一家”。async/await 是更顺手的写法：在 async 函数里写 await 订单，意思是“等这张订单出结果再往下走”，读起来像按顺序做事；但只有这个函数在等，就像你下了单照样去洗澡，页面不会卡住。订单失败时 await 会抛出错误，用 try/catch 接住，相当于准备好备用方案。
fetch 一个不存在的文件，比如 date.json，会直接进入 catch 吗？你的代码是怎么处理的？
不会直接进。服务器正常回复了 404，对 fetch 来说网络是通的，Promise 照样成功，只是 response.ok 为 false、response.status 为 404。fetch 只有在断网之类网络彻底失败时才会失败。所以我的代码在拿到 response 后检查 if (!response.ok)，不 ok 就 throw new Error(...)，主动跳进 catch，在控制台打印原因，给访客显示友好提示。
为什么双击打开 index.html 时 fetch 读不到 data.json，用 Live Server 打开就能读到？
双击打开时网址是 file:// 开头，页面是浏览器直接从硬盘读的，没有经过服务器。fetch 只支持 http 和 https，而且出于安全考虑，浏览器不允许本地打开的页面随意读取硬盘上的其他文件，否则一个下载来的恶意 html 就能偷读你的文件。Live Server 在本机启动了一个 HTTP 服务器，页面变成从 http://127.0.0.1:5500 送来的，fetch("data.json") 就是向同一个服务器再要一个文件，是正常的 HTTP 请求。
export 和 import 把代码拆到多个文件里，并说出命名导出和默认导出的区别。npm install 做了什么、node_modules 为什么不提交到 Git、package-lock.json 为什么要提交。npm create vite@latest 创建原生 JavaScript 项目 ~/code/quiz，并用 npm run dev 启动它。打开你的 links/script.js 看看：穿搭卡片、风格切换、穿搭搜索、留言表单、读取 data.json，五块功能全挤在一个文件里，已经一两百行。继续加功能，这个文件会越来越难找东西。更隐蔽的问题是：所有变量都在同一个“大房间”里。你在留言表单那块起了个变量叫 intro，昨天读 data.json 那块也有个 intro，两个名字一撞，就会报错或者互相覆盖。
打个比方。一个人住单间，东西随手一放也找得到；搬进一个团队合租的大房子，就得分房间，每个房间的东西归各自管，要借用别人房间的东西，得明确说一声“借一下”。模块就是给代码分房间：每个 .js 文件是一个独立的房间，里面的变量默认只在自己房间里有效，别的文件看不到。想让别人用，就明确地导出（export）；想用别人的，就明确地导入（import）。
今天开始做新作品“你最需要哪个东哥”测试小游戏，它会一开始就用模块来组织：题目数据一个文件，工具函数一个文件，页面逻辑一个文件。
最常用的是命名导出：在要分享的变量或函数前面加 export。
quiz/src/dom.js
export function createText(tag, className, text) {
const element = document.createElement(tag);
element.className = className;
element.textContent = text;
return element;
}这个小函数把你 DAY 19 以来反复写的三行（造元素、设 class、填文字）打包成一行。前面的 export 表示“这个函数允许别的文件使用”。在另一个文件里这样导入：
quiz/src/main.js
import { createText } from "./dom.js";
import { questions } from "./questions.js";
const title = createText("h2", "question", questions[0].text);import { createText } from "./dom.js"：从 dom.js 里导入名叫 createText 的东西。花括号里的名字必须和导出时的名字完全一致，多个用逗号隔开：import { a, b } from "..."。"./dom.js" 是路径。./ 表示“和当前文件在同一个文件夹”，不能省略；省略了，工具会以为你要找一个从 npm 装的包。没有 export 的东西，别的文件是拿不到的。比如 dom.js 里如果还有一个没加 export 的辅助变量，main.js 去导入它就会报错“没有提供这个导出”。这正是模块想要的效果：每个文件只把需要分享的东西摆到门口，其余的都是自己的内部细节，别的文件不会误用，也不会和别人重名。两个文件里各有一个叫 title 的变量，从此互不干扰。
导入进来的东西是只读的。你可以调用导入的函数、读取导入的数组，但不能写 questions = [] 把它整个换掉。想改数据，应该回到导出它的那个文件里去改。
还有一种叫默认导出，一个文件最多只能有一个，导入时不写花括号，名字可以自己起：
// 假设有一个 world-names.js（只是演示，今天不用建）
export default { gentleman: "绅士", street: "街头", thai: "泰风" };
// 在 main.js 里
import worldNames from "./world-names.js";这门课的建议是：普通的数据和函数用命名导出，名字固定，编辑器能帮你自动补全、发现拼写错误。DAY 27 学 React 时，每个组件文件会用默认导出，那是 React 社区的习惯，到时再说。
在浏览器里直接使用模块，script 标签要写成 <script type="module" src="...">。带 type="module" 的脚本自动就是延后执行的，效果和 DAY 19 学的 defer 一样。今天用 Vite 创建的项目已经替你写好了这一行。
写程序时，很多功能别人早就写好了，比如本地服务器、日期处理、图表。你不需要从零写，下载别人发布的代码就能用。这些可以下载的代码叫包（package），存放所有包的公共仓库叫 npm registry，下载和管理包的工具叫 npm（Node Package Manager，Node 包管理器）。DAY 01 装 Node.js 时，npm 已经跟着装好了。
可以把它类比成手机的应用商店：registry 是商店，包是一个个 App，npm 是负责下载、安装、更新、卸载的那个商店客户端。你今天会用到这几个命令：
| 命令 | 做什么 | 类比 |
|---|---|---|
npm create vite@latest quiz | 用最新版的 Vite 脚手架生成一个新项目 | 用装修公司的样板方案，直接交付一套毛坯房 |
npm install | 按 package.json 的清单，把所有依赖下载到 node_modules | 照着购物清单把东西一次买齐 |
npm run dev | 运行 package.json 里 scripts 下名为 dev 的命令 | 按下写好标签的快捷按钮 |
npx serve | 临时下载并运行某个包的命令，不写进项目 | 借来用一次就还 |
npm 默认把包装在当前项目的文件夹里，每个项目各装各的，互不影响。quiz 项目用的 Vite 版本，和将来 dongge-react 项目用的版本可以不同。你可能在网上看到 npm install -g 这种“全局安装”的写法，它会把包装到整台电脑上，容易造成版本混乱，这门课不需要它，临时用一下的工具用 npx 就好。
每个 npm 项目的根目录都有一个 package.json，记录项目叫什么、依赖哪些包、有哪些常用命令。今天用 Vite 创建的项目，生成的 package.json 大致是这样：
quiz/package.json
{
"name": "quiz",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"devDependencies": {
"vite": "^8.3.0"
}
}"name"：项目名。"private": true 表示这个项目不会被发布到 npm 上，防止误操作。"version" 是项目自己的版本号，个人项目不用管。"type": "module"：告诉 Node.js，这个项目里的 .js 文件都按模块处理，可以用 import/export。"scripts"：常用命令的快捷方式。npm run dev 实际执行的是 vite，启动开发服务器；npm run build 执行 vite build，打包出上线用的文件；npm run preview 在本地预览打包结果。"devDependencies"：开发时才需要的依赖。Vite 只在你写代码和打包时用，访客打开网页时并不需要它，所以放在这里。另一个字段 "dependencies" 放运行时需要的依赖，比如 DAY 27 的 React。"^8.3.0"：版本号前的 ^ 表示“8.3.0 或者更新的 8.x 版本都可以，但不要升到 9”。大版本号变了往往意味着不兼容的改动，所以锁住大版本。你生成的版本号可能和这里不同，以你自己的为准。运行 npm install 以后，项目里会多出两样东西。
node_modules 文件夹：所有依赖包实际存放的地方。你只写了一个 vite，但 vite 自己又依赖别的包，别的包再依赖别的包，npm 会把这一整串全部下载下来，所以这个文件夹通常有几十 MB、成千上万个文件。
package-lock.json 文件：一份精确的“购物小票”。package.json 里写的是 ^8.3.0 这样的范围，lock 文件则记下这次实际装的每个包的准确版本。以后在另一台电脑，或者在 Vercel 上运行 npm install，会照着小票装出一模一样的版本，避免“我电脑上好好的，线上却坏了”。
那么这两样东西要不要提交到 Git？
Vite 创建项目时已经生成了一个 .gitignore 文件，里面写着 node_modules 和 dist，Git 会自动忽略它们。文件名以点开头，在 Finder 里默认看不到，在终端用 ls -a 能看到。
Vite（法语“快”的意思，读作 veet）是一个前端构建工具，它做两件事。
开发时，它是一个本地服务器，作用和昨天的 Live Server 一样，还更强：你保存文件，浏览器几乎瞬间更新，而且只替换改动的那部分，页面上的状态常常能保留，这叫热更新（HMR）。它还允许你在 JavaScript 里写 import "./style.css" 引入 CSS，这是浏览器原生不支持、由 Vite 帮你处理的写法。
上线前，它是一个打包工具。npm run build 会把你所有的 JS、CSS 合并、压缩，文件名加上一串随机字符（防止浏览器用旧的缓存），输出到 dist 文件夹。上线用的是 dist 里的文件，不是你的源代码。明天部署到 Vercel 时，这一点非常重要。
为什么不能直接把源代码放上去？链接主页不就是直接放的吗？链接主页只有三个文件，确实可以。但 Vite 项目里写了 import "./style.css" 这种浏览器原生看不懂的写法，必须先由 Vite 翻译一遍；以后用了 React、TypeScript，浏览器更是一行都看不懂。打包还有两个附带的好处：压缩后文件更小，手机上打开更快；文件名带上随机字符后，每次改版文件名都会变，访客的浏览器就不会继续用缓存里的旧版本。
Vite 创建的原生 JavaScript 项目结构如下：
quiz/
├── index.html 入口页面，Vite 从这里开始
├── package.json 项目清单
├── .gitignore Git 忽略清单
├── public/ 原样复制到线上的静态文件，比如网站图标
└── src/
├── main.js 入口脚本，index.html 里引用的就是它
├── counter.js 模板自带的示例，今天会删掉
├── style.css 样式
└── assets/ 模板自带的图片，今天会删掉动手之前，先想清楚这个小游戏由哪几部分组成。DAY 18 你用 Node 写过文字版，用的是一组固定的答案；今天的网页版要让访客真的一题一题点。
数据：6 道题，每道题有一句题干和 3 个选项，每个选项对应一个世界。用对象数组表示：
{
id: 1,
text: "周五晚上，你更想怎么过？",
options: [
{ text: "晚回家的路上，有人一直陪你走到楼下", world: "thai" },
{ text: "提前订好的餐厅，到了就有位子", world: "gentleman" },
{ text: "临时决定去江边，看别人玩滑板", world: "street" },
],
}注意每个选项记的是 world，而不是选项的文字。计分只关心“这一票投给了哪个世界”，文字随时可能改写，世界的英文标识不会变。数据里存稳定的标识，页面上显示好看的文字，这是以后做数据库时也会一直遵守的习惯。
状态：游戏进行中需要记住的、会变化的信息。只有两个：现在是第几题（currentIndex，从 0 开始），以及访客目前选了哪些世界（answers 数组）。
渲染：根据当前状态把页面画出来。和 DAY 19 的 renderLooks 一个思路：状态变了，就清空重画。
打开页面 ──> renderQuestion() 画出第 1 题
访客点了一个选项 ──> answers 里记下这个选项的世界，currentIndex 加 1
├─ 还有题 ──> renderQuestion() 画下一题
└─ 答完了 ──> renderFinished() 显示结果（今天先显示选择记录，明天做计分）题目文案也守住“说事情不说情话”：每个选项写一个具体的场景或动作，比如“他把外套脱下来罩在你头上”，而不是“他会一直宠着你”。具体的场景让人有画面，也更像东哥本人会做的事。
检查 Node.js 版本
node -v
npm -v用 Vite 创建 quiz 项目
cd ~/code
npm create vite@latest quiz第一次运行可能问 Need to install the following packages: create-vite ... Ok to proceed? (y)，输入 y 回车。接下来会出现几个选择题，用方向键移动、回车确认：
Select a framework：选 Vanilla（原生，不用任何框架）。Select a variant：选 JavaScript。Install with npm and start now?：选 No。今天要一步步手动做，看清每一步。最后提示 Done，并告诉你接下来运行 cd quiz、npm install、npm run dev。
npm create vite@latest quiz -- --template vanilla。中间的 -- 不能漏，它表示后面的参数是传给 Vite 脚手架的。安装依赖，看看多了什么
cd ~/code/quiz
ls -a
npm install
ls -a
cat .gitignore启动开发服务器，体验热更新
npm run dev终端里出现 Local: http://localhost:5173/，在浏览器打开它，能看到 Vite 的示例页。用 VS Code 打开项目（另开一个终端标签页运行 code ~/code/quiz），在 src/main.js 里把 Get started 改成 你最需要哪个东哥，保存。
清理模板
在 VS Code 左侧文件列表里删掉 src/counter.js 和整个 src/assets 文件夹，打开 src/style.css 把内容全部删空。public 里的 favicon.svg 是网站图标，先留着。然后把 index.html 整个替换成：
quiz/index.html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>你最需要哪个东哥</title>
</head>
<body>
<main class="page">
<header class="quiz-header">
<p class="brand">三岁的东哥</p>
<h1>你最需要哪个东哥</h1>
<p class="hint">6 道题，凭第一感觉选。</p>
</header>
<div id="app"></div>
</main>
<script type="module" src="/src/main.js"></script>
</body>
</html>lang="zh-CN" 告诉浏览器页面是简体中文。题目和选项都会由 JavaScript 画进 #app。最后一行用 type="module" 引入入口脚本，路径开头的 / 表示从项目根目录算起。
这时浏览器会报错，因为 main.js 还在引用刚删掉的文件。没关系，接下来就重写它。
写工具模块 dom.js
在 src 里新建 dom.js，写入上午第 2 节的 createText 函数（带 export）。
写 6 道题的数据
在 src 里新建 questions.js。注意每道题三个选项的顺序是打乱的，免得访客发现“第一个永远是绅士”。你可以按自己的风格改写题目，但每个选项都要对应 gentleman、street、thai 之一，而且每道题三个世界各出现一次。
quiz/src/questions.js
export const questions = [
{
id: 1,
text: "周五晚上，你更想怎么过？",
options: [
{ text: "晚回家的路上，有人一直陪你走到楼下", world: "thai" },
{ text: "提前订好的餐厅，到了就有位子", world: "gentleman" },
{ text: "临时决定去江边，看别人玩滑板", world: "street" },
],
},
{
id: 2,
text: "在陌生的城市迷路了，你希望身边的人：",
options: [
{ text: "打开地图，一分钟规划好路线", world: "gentleman" },
{ text: "说“那就随便走走，说不定有好吃的”", world: "street" },
{ text: "走在靠马路的一侧，让你别低头看手机", world: "thai" },
],
},
{
id: 3,
text: "出门时突然下雨了：",
options: [
{ text: "他说跑两步就到，拉着你一起冲过去", world: "street" },
{ text: "他把外套脱下来，罩在你头上", world: "thai" },
{ text: "他包里一直放着一把折叠伞", world: "gentleman" },
],
},
{
id: 4,
text: "你最想看东哥的哪条视频？",
options: [
{ text: "穿着马甲打斯诺克，一杆清台", world: "gentleman" },
{ text: "缠好绑手带，对着沙袋打完一整轮", world: "thai" },
{ text: "踩着 BMX 在广场上练新动作", world: "street" },
],
},
{
id: 5,
text: "工作上受了委屈，你更想听到：",
options: [
{ text: "“走，先去吃那家新开的店，吃完再说。”", world: "street" },
{ text: "“先说说发生了什么，我们一起想怎么处理。”", world: "gentleman" },
{ text: "“明天我去公司楼下接你下班。”", world: "thai" },
],
},
{
id: 6,
text: "出门见面，你希望他穿：",
options: [
{ text: "运动背心配泰拳短裤，刚练完拳", world: "thai" },
{ text: "Oversize 卫衣、Baggy 裤、一双 Vans", world: "street" },
{ text: "衬衫、马甲、擦亮的皮鞋", world: "gentleman" },
],
},
];重写 main.js：一题一题显示，记录选择
把 src/main.js 的内容全部替换成下面的代码。先自己对照上午第 7 节的流程图读一遍，再敲。
quiz/src/main.js
import "./style.css";
import { questions } from "./questions.js";
import { createText } from "./dom.js";
const app = document.querySelector("#app");
let currentIndex = 0;
// 明天“再测一次”要把它换成新的空数组，所以用 let
let answers = [];
function renderQuestion() {
const question = questions[currentIndex];
app.innerHTML = "";
const progress = createText("p", "progress", `第 ${currentIndex + 1} 题 / 共 ${questions.length} 题`);
const title = createText("h2", "question", question.text);
const optionList = document.createElement("div");
optionList.className = "options";
question.options.forEach((option) => {
const button = createText("button", "option", option.text);
button.type = "button";
button.addEventListener("click", () => {
chooseOption(option.world);
});
optionList.append(button);
});
app.append(progress, title, optionList);
}
function chooseOption(world) {
answers.push(world);
currentIndex += 1;
if (currentIndex < questions.length) {
renderQuestion();
} else {
renderFinished();
}
}
function renderFinished() {
app.innerHTML = "";
const title = createText("h2", "question", "答完了");
const detail = createText("p", "progress", `你的选择：${answers.join("、")}`);
app.append(title, detail);
console.log("answers:", answers);
}
renderQuestion();逐段看：
import "./style.css" 只引入不取名字，意思是“让这份 CSS 生效”，这是 Vite 提供的能力。renderQuestion：按 currentIndex 取出当前题，清空 #app，画出进度、题干和三个选项按钮。每个按钮的点击处理函数通过箭头函数“记住”了自己对应的 option.world。chooseOption：把选中的世界推进 answers，题号加 1，还有题就画下一题，没有就画结束页。renderFinished：今天先把选择记录用顿号连起来显示，并打印到控制台，明天换成真正的结果页。写样式
quiz/src/style.css
* {
box-sizing: border-box;
}
body {
margin: 0;
font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Helvetica Neue", sans-serif;
background: #f6f4ef;
color: #1f2a2e;
}
.page {
max-width: 480px;
margin: 0 auto;
padding: 32px 16px 48px;
}
.quiz-header {
margin-bottom: 24px;
text-align: center;
}
.brand {
margin: 0;
font-size: 0.875rem;
color: #888;
}
.quiz-header h1 {
margin: 8px 0;
font-size: 1.75rem;
}
.hint {
margin: 0;
color: #666;
}
.progress {
margin: 0 0 8px;
font-size: 0.875rem;
color: #888;
}
.question {
margin: 0 0 16px;
font-size: 1.25rem;
line-height: 1.5;
}
.options {
display: flex;
flex-direction: column;
gap: 12px;
}
.option {
padding: 14px 16px;
border: 1px solid #d6d0c4;
border-radius: 12px;
background: #fff;
color: inherit;
font: inherit;
line-height: 1.5;
text-align: left;
cursor: pointer;
}
.option:hover {
border-color: #1f2a2e;
}全是你学过的属性。max-width: 480px 加 margin: 0 auto 让内容在电脑上也保持手机宽度并居中，这个小游戏主要在手机上玩。选项按钮做得又宽又高，手指好点。
初始化 Git，确认 node_modules 被忽略
新开一个终端标签页（开发服务器那个继续开着）：
cd ~/code/quiz
git init
git statusgit add .
git commit -m "用 Vite 创建测试小游戏：6 道题，逐题显示并记录选择"今天只在本地提交，明天部署时再推到 GitHub。
用 DAY 18 的思路预想明天的计分
回头看一眼 ~/code/learn/js/quiz-cli.js 里你写的计分函数。现在 answers 数组的样子和那时的固定答案一样，都是由 gentleman、street、thai 组成的数组。在纸上写下：明天要把哪个函数搬过来、放在哪个新文件里、需要 export 什么。明天上午会用到。
npm install，或者在错误的文件夹里运行。先 pwd 确认在 ~/code/quiz，再 npm install。ls -a 看看它还在不在，里面有没有 node_modules 这一行。npm install 做了什么？node_modules 为什么不提交到 Git？
npm install 读取 package.json 里列出的依赖，连同这些依赖自己的依赖，从 npm 仓库下载下来放进 node_modules 文件夹，并按 package-lock.json 锁定准确版本（没有 lock 文件就生成一份）。node_modules 不提交，因为它非常大、文件极多；它随时可以用 package.json 和 package-lock.json 重新生成；而且部分内容和操作系统有关，Mac 上装的不一定能在 Vercel 的 Linux 服务器上用。Vercel 部署时会自己运行 npm install。package-lock.json 要提交，它保证各处装出同样的版本。
命名导出和默认导出有什么区别？如果 questions.js 里写的是 export const questions = [...]，main.js 里写 import questions from "./questions.js" 会怎样？
命名导出用 export 加名字，一个文件可以有多个，导入时必须写花括号、名字必须一致；默认导出用 export default，一个文件最多一个，导入时不写花括号、名字可以自己起。题目里 questions.js 用的是命名导出，main.js 却按默认导出的写法导入，会报错说这个模块没有默认导出。应该写 import { questions } from "./questions.js"。
npm run dev 和 npm run build 分别做什么？上线时用的是哪一个的结果？
npm run dev 运行 package.json 里的 dev 脚本，也就是 vite，启动本地开发服务器，改代码后浏览器热更新，只用于开发。npm run build 运行 vite build，把代码合并、压缩，输出到 dist 文件夹。上线用的是 build 生成的 dist 里的文件。
score.js 模块，算出每个世界的得分和最高分的世界。npm run build 和输出目录 dist 分别是什么意思，并把 quiz 部署上线。昨天的小游戏已经能一题一题地走完，answers 数组里存着访客的 6 个选择，比如 ["thai", "gentleman", "street", "gentleman", "street", "thai"]。今天上午把“算结果”这件事做完。DAY 18 你在 Node 里写过文字版的计分，思路完全一样，今天把它整理成一个独立的模块 src/score.js。
为什么单独放一个文件？计分是整个小游戏最核心的规则，它和页面长什么样没有关系：输入一个答案数组，输出一个结果。把它和画页面的代码分开，以后改页面不会误伤计分，改计分也不用在一堆 createElement 里翻找。DAY 51 学单元测试时，你第一个要测的就是这个文件。
第一步是数票：
quiz/src/score.js
export function countScores(answers) {
const scores = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((world) => {
scores[world] += 1;
});
return scores;
}scores[world] += 1 给对应的世界加一票。这里必须用方括号，因为 world 是一个变量，它的值才是键名，这是 DAY 17 验收题的内容。{ gentleman: 2, street: 2, thai: 2 }。数完票，要找出票最多的世界。注意是“世界们”，因为可能不止一个。
const scores = countScores(answers);
const maxScore = Math.max(...Object.values(scores));
const topWorlds = Object.keys(scores).filter((world) => scores[world] === maxScore);Object.values(scores)：取出对象里所有的值，得到一个数组，比如 [3, 2, 1]。Math.max(...数组)：Math.max 接收的是一个个单独的数字，而不是一个数组。前面的三个点是 DAY 17 学的展开运算符，把数组“拆开”成一个个参数，相当于写 Math.max(3, 2, 1)，结果是 3。Object.keys(scores)：取出所有的键，["gentleman", "street", "thai"]。.filter(...)：只留下得分等于最高分的世界。正常情况下 topWorlds 里只有一个世界；同分时会有两个或三个。这样写的好处是，“有没有同分”变成了一个很简单的判断：topWorlds.length === 1 就是没同分，直接出结果；大于 1 就进入下一节的同分处理。
DAY 18 的验收题问过：两个世界同分时，你的计分函数会怎样？如果你当时用的是“遍历时遇到更大的才替换”的写法，同分时永远是排在前面的世界赢，也就是绅士永远占便宜。这不是一个“规则”，而是代码顺序带来的偶然结果。
先算一算，6 道题、每题投给三个世界之一，同分只可能出现两种分布：
为什么没有 2 : 2 : 1？因为加起来只有 5，不够 6 道题。常见的处理规则有三种：
| 规则 | 做法 | 优点 | 问题 |
|---|---|---|---|
| 并列结果 | 显示“你同时需要绅士和街头” | 最诚实 | 要多写几套组合文案，分享卡片也不好设计 |
| 固定优先级 | 同分时永远按绅士、街头、泰风的顺序选 | 简单 | 对排在后面的世界不公平，还是偶然 |
| 最近的选择优先 | 同分时，看访客最后选的是哪个同分世界 | 有道理，结果仍然只有一个 | 要向访客说明一句 |
这门课用第三种：同分时，从最后一题往前找，第一个属于同分世界的选择就是结果。理由是：越往后，访客对题目越熟悉，选择越接近真实感受；而且最后一题问的是“出门见面，你希望他穿什么”，本身就很能代表偏好。同时在结果页上写一句说明，让访客知道发生了什么，而不是暗中替他决定。
quiz/src/score.js
export function pickWorld(answers) {
const scores = countScores(answers);
const maxScore = Math.max(...Object.values(scores));
const topWorlds = Object.keys(scores).filter((world) => scores[world] === maxScore);
if (topWorlds.length === 1) {
return { world: topWorlds[0], topWorlds, scores };
}
// 同分：从最后一题往前找，第一个属于同分世界的选择就是结果
for (let i = answers.length - 1; i >= 0; i -= 1) {
if (topWorlds.includes(answers[i])) {
return { world: answers[i], topWorlds, scores };
}
}
return { world: topWorlds[0], topWorlds, scores };
}world，还带上 topWorlds（同分的有哪些）和 scores（每个世界几票），结果页要用它们写说明。{ world: ..., topWorlds, scores } 里后两项是简写，等于 topWorlds: topWorlds。for (let i = answers.length - 1; i >= 0; i -= 1)：DAY 14 的 for 循环，这次是倒着走，从最后一个下标数到 0。topWorlds.includes(answers[i])：这一题的选择属于同分世界吗？是就返回它，循环和函数一起结束。细心的话你会发现：6 道题时，同分只有 3 : 3 : 0 和 2 : 2 : 2 两种，这两种情况下最后一题的选择一定属于同分世界，所以循环第一次就会返回。那为什么还要写成循环？因为题目数量以后可能变。假如加到 7 道题，就可能出现 3 : 3 : 1，而最后一题恰好投给了只有 1 票的那个世界，这时就需要继续往前找。代码按通用情况写，改题目时就不用回来改规则。
用几组答案检验一下：
| answers | 得分 | 结果 |
|---|---|---|
| gentleman, street, gentleman, thai, gentleman, street | 绅士 3、街头 2、泰风 1 | 绅士，没有同分 |
| thai, gentleman, street, gentleman, street, thai | 各 2 票 | 泰风，最后一题选的是泰风 |
| street, gentleman, gentleman, street, street, gentleman | 绅士 3、街头 3、泰风 0 | 绅士，最后一题选的是绅士 |
| 假设 7 题：gentleman, street, gentleman, street, gentleman, street, thai | 绅士 3、街头 3、泰风 1 | 街头，最后一题的泰风不在同分里，往前一题是街头 |
结果页是访客最可能截图分享的地方，文案决定了别人怎么看待“三岁的东哥”这个号。守住“说事情不说情话”，具体有三条标准：
每个世界准备五样东西：短名（绅士）、结果名（绅士东哥）、给人的感觉（安全感）、一句总结、一段细节，再加一句推荐看哪类视频，把测试和内容连起来。下午的 results.js 就是这样组织的。你可以改写成自己的话，但写完每一句都问自己：这句话是在说一件事，还是在说一句情话？
访客在手机上做完测试，最自然的动作是截图发给朋友或者发到社交平台。结果卡片要为这个动作设计：
aspect-ratio: 3 / 4 让卡片永远是宽 3 高 4 的竖版比例，截图后放进朋友圈或小红书都不会被裁得很难看。aspect-ratio 是一个你第一次见的属性，意思就是“宽高比”。内容太多时，卡片会自动长高，不会把文字截断。card-gentleman、card-street、card-thai 之一，用 DAY 09 学的 CSS 变量定义每套的背景色、文字色和强调色，结构只写一份。还有两个容易忽略的细节。一是文字和背景的对比度：街头卡片是亮橙色底，如果配白字，在阳光下的手机屏幕上会看不清，所以用接近黑色的字；绅士和泰风是深色底，用浅色字。二是字数：卡片宽度只有手机屏幕那么宽，细节那一段控制在两三行，写长了卡片会被撑得很高，截图要分两张，别人就懒得转发了。写完文案后，一定在最小的手机尺寸下看一眼。
DAY 03 和 DAY 12 你部署的都是纯 HTML 网站：仓库里的文件就是线上的文件，Vercel 原样发出去。Vite 项目不一样。昨天讲过，你的源代码里有 import "./style.css" 这种浏览器看不懂的写法，必须先经过 Vite 打包，生成 dist 文件夹，上线的是 dist 里的内容。
所以 Vercel 部署 Vite 项目时，要在它的服务器上把你在本地做的事重做一遍：
你 git push 到 GitHub
└─ Vercel 收到通知，把仓库下载到它的服务器
└─ Install Command：npm install 按 package.json 和 lock 文件装依赖
└─ Build Command：npm run build 运行 vite build，生成 dist 文件夹
└─ Output Directory：dist 只把 dist 里的文件发布到线上导入项目时，Vercel 会看你的 package.json，认出这是 Vite 项目，把 Framework Preset（框架预设）设为 Vite，并自动填好这三项。你要做的是核对：
| 设置项 | 应该是 | 意思 |
|---|---|---|
| Framework Preset | Vite | 按 Vite 项目的方式处理 |
| Build Command | npm run build（或 vite build） | 怎么把源代码变成上线文件 |
| Output Directory | dist | 上线文件在哪个文件夹 |
| Install Command | npm install | 怎么安装依赖 |
如果 Framework Preset 显示的是 Other，说明没识别出来，手动选成 Vite 即可。最常见的部署事故就是输出目录不对：Vercel 发布了整个仓库而不是 dist，线上打开是空白页或者 404。
上线前，先在本地跑一遍同样的流程：npm run build 看有没有报错，再用 npm run preview 打开打包后的版本。本地能顺利 build 的项目，在 Vercel 上基本也能。本地 build 报错，Vercel 上一定报错。
第一次部署成功后，以后的流程和链接主页一样：本地改代码、commit、push，Vercel 自动重新安装、重新打包、重新发布，一两分钟后线上就是新版本。每次部署在 Vercel 的 Deployments 页面都有记录，能看到当时的构建日志；万一新版本出了问题，可以在那里把旧版本重新设为线上版本。这就是为什么每次 push 前都值得先在本地跑一次 npm run build：把错误挡在自己电脑上，比在线上发现要轻松得多。
新建 score.js，并用几组答案验证
确认开发服务器在运行（cd ~/code/quiz 后 npm run dev）。在 src 里新建 score.js，写入上午第 1 节的 countScores 和第 3 节的 pickWorld，两个函数都带 export。
模块里的函数不会自动出现在控制台里，没法直接在控制台调用。临时在 main.js 的 import 下面加几行测试：
quiz/src/main.js（临时测试，验证完删掉）
import { pickWorld } from "./score.js";
console.log(pickWorld(["gentleman", "street", "gentleman", "thai", "gentleman", "street"]));
console.log(pickWorld(["thai", "gentleman", "street", "gentleman", "street", "thai"]));
console.log(pickWorld(["street", "gentleman", "gentleman", "street", "street", "gentleman"]));
console.log(pickWorld(["gentleman", "street", "gentleman", "street", "gentleman", "street", "thai"]));写结果文案 results.js
在 src 里新建 results.js。下面是示例，建议你按上午第 4 节的三条标准改写成自己的话。
quiz/src/results.js
export const results = {
gentleman: {
label: "绅士",
name: "绅士东哥",
feeling: "安全感",
summary: "你需要一个把事情提前安排好的人。",
detail: "订好的位子，准时的见面，出门前看过的天气预报。斯诺克要一杆一杆算清楚，他过日子也是这样。",
recommend: "推荐看：穿马甲打斯诺克的那几条视频。",
},
street: {
label: "街头",
name: "街头东哥",
feeling: "心动",
summary: "你需要生活里多一点计划外的事。",
detail: "一条没走过的路，一家临时决定去的小店，一个练了一下午才落地的 BMX 动作。不用每件事都想好再出发。",
recommend: "推荐看：广场上练滑板和 BMX 的那几条视频。",
},
thai: {
label: "泰风",
name: "泰风东哥",
feeling: "被保护感",
summary: "你需要一个遇到事会先站出来的人。",
detail: "夜里走在靠马路的那一侧，人多的地方走在你前面。泰拳每天练的是出拳和防守，放在生活里，就是有麻烦他先上。",
recommend: "推荐看：缠绑手带、打沙袋的训练视频。",
},
};把结束页换成结果页，加上“再测一次”
打开 main.js，做三处修改。第一，import 区域变成这样：
quiz/src/main.js
import "./style.css";
import { questions } from "./questions.js";
import { results } from "./results.js";
import { pickWorld } from "./score.js";
import { createText } from "./dom.js";第二，在 chooseOption 里把 renderFinished() 改成 renderResult()。第三，删掉整个 renderFinished 函数，换成下面两个函数：
quiz/src/main.js
function renderResult() {
const { world, topWorlds } = pickWorld(answers);
const result = results[world];
app.innerHTML = "";
const card = document.createElement("section");
card.className = `result-card card-${world}`;
card.append(
createText("p", "card-brand", "三岁的东哥 · 测试结果"),
createText("p", "card-label", "你最需要的是"),
createText("h2", "card-title", result.name),
createText("p", "card-feeling", `他给你的是：${result.feeling}`),
createText("p", "card-summary", result.summary),
createText("p", "card-detail", result.detail),
createText("p", "card-footer", "小红书 / TikTok 搜：三岁的东哥")
);
app.append(card);
if (topWorlds.length > 1) {
const names = topWorlds.map((item) => results[item].label).join("、");
app.append(
createText("p", "tie-note", `你在${names}之间打了个平手，按你最后的选择，结果算作${result.label}。`)
);
}
app.append(createText("p", "recommend", result.recommend));
app.append(createText("p", "share-hint", "截图这张卡片，发给也在看东哥的朋友。"));
const restartButton = createText("button", "restart", "再测一次");
restartButton.type = "button";
restartButton.addEventListener("click", restart);
app.append(restartButton);
}
function restart() {
currentIndex = 0;
answers = [];
renderQuestion();
}逐段看：const { world, topWorlds } = pickWorld(answers) 是 DAY 17 学的解构，从返回的对象里一次取出两个值。用 world 从 results 里取出对应的文案。卡片的 class 是 result-card 加上 card-gentleman 这样的世界 class，颜色靠后者切换。card.append 一次放进七行文字。同分时用 map 把英文标识换成中文短名，再用顿号连起来写一句说明。restart 把两个状态恢复成初始值，再画第 1 题，这就是昨天 answers 用 let 的原因。
给结果卡片加样式
在 src/style.css 最后加上：
quiz/src/style.css
/* ===== 结果卡片（DAY 24） ===== */
.result-card {
display: flex;
flex-direction: column;
gap: 8px;
width: 100%;
max-width: 360px;
aspect-ratio: 3 / 4;
margin: 0 auto;
padding: 28px 24px;
border-radius: 20px;
background: var(--card-bg);
color: var(--card-text);
}
.card-gentleman {
--card-bg: #1f2a2e;
--card-text: #f4efe6;
--card-accent: #c9a96e;
}
.card-street {
--card-bg: #ff5a1f;
--card-text: #141414;
--card-accent: #ffffff;
}
.card-thai {
--card-bg: #9e1b1f;
--card-text: #fff7ec;
--card-accent: #ffd166;
}
.result-card p {
margin: 0;
}
.card-brand {
font-size: 0.75rem;
letter-spacing: 0.1em;
opacity: 0.8;
}
.result-card .card-label {
margin-top: 24px;
font-size: 0.875rem;
}
.card-title {
margin: 0;
font-size: 2.25rem;
line-height: 1.2;
}
.card-feeling {
font-weight: 600;
color: var(--card-accent);
}
.card-summary {
font-size: 1.125rem;
line-height: 1.6;
}
.card-detail {
font-size: 0.9375rem;
line-height: 1.7;
opacity: 0.9;
}
.result-card .card-footer {
margin-top: auto;
font-size: 0.75rem;
opacity: 0.8;
}
.tie-note,
.recommend,
.share-hint {
max-width: 360px;
margin: 16px auto 0;
font-size: 0.875rem;
line-height: 1.6;
color: #555;
}
.restart {
display: block;
width: 100%;
max-width: 360px;
margin: 24px auto 0;
padding: 14px;
border: none;
border-radius: 12px;
background: #1f2a2e;
color: #fff;
font: inherit;
cursor: pointer;
}两个要点。第一，.card-footer 的 margin-top: auto：在纵向的 Flexbox 里，它会吃掉所有剩余空间，把“小红书 / TikTok 搜”这一行推到卡片最底部。第二，.card-label 和 .card-footer 前面加了 .result-card，是因为上面的 .result-card p { margin: 0; } 比单独一个 class 更“具体”，会盖掉它们的 margin；前面加一层 .result-card，两个 class 比一个 class 加一个标签更具体，就能赢回来。
专门测试同分
按下面的顺序作答，制造一次 2 : 2 : 2：第 1 题选泰风的选项（陪你走到楼下），第 2 题选绅士（打开地图），第 3 题选街头（拉着你冲过去），第 4 题选绅士（斯诺克），第 5 题选街头（先去吃新店），第 6 题选泰风（泰拳短裤）。
在手机尺寸下检查，并截一张图
打开开发者工具的手机模拟模式，分别选 iPhone SE（小屏）和一款大屏手机，走完一遍测试。在 Elements 面板里找到卡片对应的 section class="result-card ..." 那一行，右键选 Capture node screenshot（截取节点屏幕截图），Chrome 会只截这张卡片并下载成图片。
如果想在自己的手机上试，停掉开发服务器，改用 npm run dev -- --host 启动，终端会多出一行 Network: 地址。手机和电脑连同一个 Wi-Fi，在手机浏览器里输入这个地址即可。
本地打包并预览
按 Ctrl + C 停掉开发服务器，运行：
cd ~/code/quiz
npm run build
ls dist dist/assets
npm run previewhttp://localhost:4173/，打开后小游戏一切正常。这就是线上将要运行的版本。提交并推到 GitHub
在浏览器打开 https://github.com/new，Repository name 填 quiz，公开或私有都可以，不要勾选添加 README、.gitignore 或 license（本地已经有了）。创建后，在终端运行（把“你的用户名”换成你的 GitHub 用户名）：
cd ~/code/quiz
git add .
git commit -m "完成计分、同分处理和结果卡片"
git branch -M main
git remote add origin https://github.com/你的用户名/quiz.git
git push -u origin maingit branch -M main 确保分支名是 main；remote add 告诉本地仓库 GitHub 上的地址；push -u 第一次推送并记住对应关系，以后只要 git push。如果你在 DAY 02 用过 GitHub CLI，也可以用 gh repo create quiz --public --source=. --remote=origin --push 一步完成。
在 Vercel 导入并核对构建设置
打开 Vercel 控制台，点 Add New，选 Project，在 Import Git Repository 列表里找到 quiz，点 Import。在配置页面：
quiz。npm run build 或 vite build，Output Directory 是 dist，Install Command 是 npm install。都是自动填好的就不要改。./。点 Deploy，观察构建日志：你会看到它依次安装依赖、运行 vite build、列出 dist 里的文件。
quiz-xxxx.vercel.app 的网址，打开就是你的小游戏。以后这些设置在项目的 Settings 里的 Build and Deployment 页面可以查看和修改。在手机上完整走一遍，并准备明天的验收
用手机打开线上网址，做一遍测试，截图结果卡片，发到自己的聊天窗口里看看缩略图效果。然后把网址发给两位朋友，请他们在手机上做一遍。你在旁边看，或者请他们做完后语音告诉你。记下三类信息：
顺手把入口放进链接主页
打开 ~/code/links/index.html，在平台按钮区域下面加一个指向小游戏网址的普通链接，文字可以是“测一测：你最需要哪个东哥”，记得带上 target="_blank" rel="noopener"。保存后 commit 并 push。
results[world] 取不到东西。通常是 questions.js 里某个选项的 world 拼错了（比如写成 gentlemen），results 里没有这个键。检查所有选项的拼写。DAY 26 学了 TypeScript 的字面量类型，这种错误编辑器会直接标红。npm run build，本地的报错和线上一样，而且更好读。本地修好、提交、push，Vercel 会自动重新部署。请两位朋友在手机上做一遍，记下他们卡住或觉得别扭的地方。
这道题没有标准答案，交付物是一份反馈清单。一份合格的清单应该包括：朋友是谁、用的什么手机；每处问题发生在哪一步（第几题、结果页、截图时）；对方的原话，而不是你的概括；你的初步判断（是题目文案问题、结果文案问题还是交互问题）。常见的反馈有：某道题三个选项都不像自己；结果名看不出和东哥有什么关系；小屏手机上卡片太长截不全；不知道截图后发到哪里。今天记下来就好，DAY 31 做 React 版时逐条处理。
6 道题时，同分有哪几种可能的分布？你的 pickWorld 遇到同分时怎么决定结果？为什么要写成倒序循环，而不是直接取最后一题？
只有 3 : 3 : 0 和 2 : 2 : 2 两种，2 : 2 : 1 加起来不够 6。遇到同分时，从最后一题往前找，第一个属于同分世界的选择就是结果，并在结果页写一句说明。6 道题时最后一题一定属于同分世界，但如果以后题目数变成 7 道，可能出现 3 : 3 : 1 且最后一题投给了只有 1 票的世界，这时要继续往前找。写成循环，改题目数量时规则依然正确。
在 Vercel 上部署 Vite 项目时，Build Command 和 Output Directory 分别填什么？如果 Output Directory 填错了会怎样？
Build Command 是 npm run build（等于运行 vite build），它在 Vercel 的服务器上把源代码打包；Output Directory 是 dist，告诉 Vercel 打包结果在哪个文件夹，只发布这个文件夹里的内容。如果填错，比如留空或者填成项目根目录，Vercel 会发布未打包的源代码或者找不到文件，线上通常是空白页、404，或者样式和脚本加载失败。
querySelector 可能返回 null 的问题，用 if 判断把类型收窄，而不是用 ! 或 any 把错误藏起来。~/code/quiz 从 JavaScript 迁移到 TypeScript：加上官方的 tsconfig.json，改文件扩展名，逐个修掉 npx tsc 报出的错误。从今天开始进入阶段 3，Claude 的角色也从“老师”变成“审稿人”：代码你先自己写，写完再请它审查。先回头看看过去一周遇到过的几类错误：
gentlemen，页面一直正常，直到有人答完题，结果页才报 Cannot read properties of undefined。response.ok，或者漏写一个 await，结果 data.platforms 是 undefined。querySelector 返回 null，接着调用 append 就报错。这些错误有个共同点：代码写错的那一刻没有任何提示，要等页面真的运行到那一行才爆出来。有的在你自己测试时就能发现，有的要等某位访客走到某个特定的分支才出现，比如只有选到某个选项、只有同分时才会运行的代码。
打个比方。JavaScript 像是写完一份合同直接寄出去，对方签的时候才发现金额写错了。TypeScript 则像是给合同配了一位随时在旁边的审校：你每写一个字，它就对照规则检查一遍，“这里应该填数字，你填了文字”“这个人名在名单里查不到”。错误在你写的时候就被标出来，而不是寄出去之后。
TypeScript（简称 TS）是在 JavaScript 基础上加了类型的语言。所有合法的 JavaScript 代码，基本上都是合法的 TypeScript 代码；TypeScript 只是多了一种写法：在变量、参数后面加上冒号和类型，说明“这里应该放什么样的值”。
function greet(name: string): string {
return `你好，${name}`;
}
greet("小林"); // 正确
greet(3); // 编辑器立刻标红：数字不能传给要求 string 的参数name: string 表示参数 name 必须是字符串，括号后面的 : string 表示这个函数返回字符串。
关键的一点：浏览器看不懂 TypeScript。浏览器只运行 JavaScript。所以 TS 代码在交给浏览器之前，要先把所有类型标注擦掉，变回普通的 JS。上面那段代码擦掉类型后就是：
function greet(name) {
return `你好，${name}`;
}那检查是谁在做？在你的 Vite 项目里，分工是这样的：
| 谁 | 什么时候 | 做什么 |
|---|---|---|
| VS Code | 你敲代码的同时 | 实时检查类型，错误处画红色波浪线，鼠标放上去看原因 |
tsc 命令 | 你手动运行 npx tsc，或 npm run build 时 | 检查整个项目，把所有类型错误列出来；有错误就失败 |
| Vite 开发服务器 | npm run dev 时 | 只擦掉类型，不检查，所以很快 |
最后一行很重要：npm run dev 时即使有类型错误，页面照样能打开。这是 Vite 故意的设计，为了让开发时的刷新足够快。真正的把关在两个地方：写代码时看 VS Code 的红线，上线前 npm run build 会先运行 tsc，有一个类型错误就不让打包。DAY 24 你已经知道 Vercel 部署时运行的就是 npm run build，所以类型错误根本到不了线上。
这就是今天验收题的答案方向：TypeScript 在写代码时报错，而不是在用户打开网页时报错。
也要清楚 TypeScript 管不到什么。它检查的是“形状”：这里该是数字还是字符串、这个对象有没有这个属性、这个值会不会是 null。它不检查“逻辑”：如果你把同分规则写成了“取第一题”而不是“取最后一题”，类型完全正确，TS 一声不吭。逻辑对不对，要靠你自己测试，DAY 51 会学用自动化测试来守住它。另外，TS 只能检查你代码里写死的东西，从网络上读来的数据（比如 DAY 22 的 data.json）到底长什么样，要等运行时才知道，DAY 44 学 Zod 时会处理这个问题。
最常用的三个基本类型，对应 DAY 13 学的三种数据：
let nickname: string = "小林";
let score: number = 0;
let finished: boolean = false;
score = 3; // 可以，还是数字
score = "三分"; // 报错：不能把 string 赋值给 number变量名后面的 : string 叫类型注解。一旦声明了 score 是 number，以后就只能给它赋数字。
不过大多数时候你不用写注解，因为 TypeScript 会根据初始值自己推断：
let nickname = "小林"; // TS 推断为 string
let score = 0; // TS 推断为 number
score = "三分"; // 同样报错这叫类型推断。在 VS Code 里把鼠标停在变量名上，会弹出它被推断成的类型。一个实用的原则：变量有初始值时交给推断；函数的参数必须写类型，因为 TS 没法从别处猜出调用者会传什么进来；函数的返回值可以推断，但导出给别的文件用的函数，建议写清楚，相当于给使用者一份说明书。
const nickname = "小林" 上，会看到类型是 "小林" 而不是 string。这是因为 const 不能再改，TS 推断得更精确。这种类型叫字面量类型，明天会专门讲，它正是解决 gentlemen 拼写错误的武器。数组的类型写成“元素类型加一对方括号”：
let answers: string[] = [];
answers.push("street"); // 可以
answers.push(3); // 报错：数组里只能放字符串为什么这里必须写注解？因为空数组 [] 没法推断出将来要放什么。昨天的 main.js 里就有一句 let answers = []，今天迁移时你会看到 TS 为它报错。
对象的类型，是把每个属性的名字和类型列出来，属性之间用分号隔开：
let platform: { name: string; url: string; color: string } = {
name: "小红书",
url: "https://example.com/xiaohongshu",
color: "#ff2442",
};
platform.name = "TikTok"; // 可以
platform.fans = 1000; // 报错：类型里没有 fans 这个属性对象数组就是把对象类型后面加上方括号：{ name: string; url: string }[]。
还有一种情况今天会遇到：对象的键不是固定写死的，而是来自一个变量。比如计票板 scores[world]，world 是一个字符串变量。这时要用索引签名告诉 TS“这个对象可以用任意字符串当键，值都是数字”：
const scores: { [world: string]: number } = { gentleman: 0, street: 0, thai: 0 };
const world = "street";
scores[world] += 1; // 可以方括号里的 world: string 表示“键是字符串”，这里的 world 只是一个起说明作用的名字，换成 key 也一样。冒号后面的 number 是值的类型。这种写法今天先够用，但它其实有点宽松：它允许任何字符串当键，scores["gentlemen"] 也不会报错。明天学了字面量类型，会换成更严格的写法。
函数的类型包括两部分：每个参数的类型，以及返回值的类型。
quiz/src/dom.ts
export function createText(tag: string, className: string, text: string): HTMLElement {
const element = document.createElement(tag);
element.className = className;
element.textContent = text;
return element;
}: HTMLElement 是返回值类型。HTMLElement 是浏览器内置的类型名，表示“一个 HTML 元素”。TypeScript 自带了所有 DOM 相关的类型，比如 HTMLButtonElement（按钮）、HTMLDivElement（div）、HTMLInputElement（输入框）。void，意思是“空”：function restart(): void { ... }。这里藏着一个今天会遇到的问题。document.createElement("button") 这样直接传一个写死的标签名，TS 知道你造的是按钮，返回 HTMLButtonElement，它有 type 属性。但 createText 的 tag 参数是任意字符串，TS 只能说“返回的是某种 HTML 元素”，也就是笼统的 HTMLElement，它身上没有 type 属性。所以昨天那句 restartButton.type = "button" 迁移后会报错。解决办法很简单：需要设置按钮专属属性的地方，直接用 document.createElement("button")。
箭头函数的写法一样，参数后面加类型：const double = (n: number): number => n * 2;。像 answers.forEach((world) => ...) 这种传给数组方法的回调，参数类型 TS 能从数组推断出来，不用写。
在 TypeScript 里，document.querySelector("#app") 的返回类型是 Element | null。中间那条竖线读作“或者”，意思是：可能是一个元素，也可能是 null。这正是 DAY 19 那个坑：选择器没找到时返回 null。JavaScript 让你直接用，出错了算你的；TypeScript 不让你直接用：
const app = document.querySelector("#app");
app.innerHTML = ""; // 报错：'app' is possibly 'null'.怎么让它放行？最推荐的办法是用 if 判断把 null 的情况处理掉。TS 会跟着你的判断走：判断之后的代码里，它知道这个值已经不可能是 null 了。这叫类型收窄。
quiz/src/main.ts
function getApp(): HTMLDivElement {
const element = document.querySelector<HTMLDivElement>("#app");
if (!element) {
throw new Error("页面里找不到 #app，检查 index.html");
}
return element;
}
const app = getApp();querySelector<HTMLDivElement>("#app")：尖括号里告诉 TS“我找的是一个 div”，于是返回类型变成 HTMLDivElement | null。尖括号这种写法叫泛型，明天讲。if (!element) { throw ... }：如果没找到，直接抛出一个写清原因的错误。throw 之后函数就结束了，所以 TS 知道：能走到 return 这一行的，element 一定不是 null。HTMLDivElement，不带 null。于是 const app = getApp() 得到的 app，在整个文件的任何地方用都不会再报“可能为 null”。你可能会在 Vite 模板或网上看到另一种写法：document.querySelector("#app")!，末尾加一个感叹号。它叫非空断言，意思是“相信我，这里一定不是 null”。它确实能让报错消失，但它只是让 TS 闭嘴，并没有处理问题：万一真是 null，页面照样崩溃，而且报错信息看不出原因。上面的 getApp 写法多了几行，换来的是出问题时一句清楚的中文说明。
! 或者把类型写成 any（意思是“任意类型，放弃检查”）来应付。今天请 Claude 审稿时，也请它专门找这类“藏起来”的地方。要把 quiz 改成 TypeScript，有三条路：
| 方案 | 做法 | 问题 |
|---|---|---|
| A. 重建项目 | 用 Vanilla + TypeScript 模板新建一个项目，把代码复制过去 | 新项目没有你的 Git 历史，也没连着 GitHub 仓库和 Vercel 的 quiz 项目，要重新接一遍，容易接错 |
| B. 手写配置 | 在原项目里自己写 tsconfig.json、装 TypeScript | tsconfig 选项很多，手写容易漏掉关键项，比如让 TS 认识 import "./style.css" 的那一项 |
| C. 抄官方配置 | 在旁边临时生成一个 Vanilla + TypeScript 模板当参考，把它的 tsconfig.json 和 TypeScript 版本原样搬进 quiz | 多一步生成参考模板，用完删掉即可 |
这门课选 C。它同时保住了两样东西：quiz 原有的 Git 历史、GitHub 仓库和 Vercel 部署都不用动；配置文件来自 Vite 官方模板，和你的 Vite 版本配套，不会因为手写漏项出一些莫名其妙的错。
官方模板的 tsconfig.json 里，你需要看懂这几项：
"types": ["vite/client"]：让 TS 认识 Vite 提供的功能，比如 import "./style.css"。少了它，这一行会报错。"noEmit": true：tsc 只检查，不生成 JS 文件。生成文件是 Vite 的事。"allowImportingTsExtensions": true：允许 import 时写 .ts 扩展名，比如 import { questions } from "./questions.ts"。"noUnusedLocals" 和 "noUnusedParameters"：声明了却没用到的变量和参数也算错误，逼你保持代码干净。"include": ["src"]：只检查 src 文件夹里的文件。你会发现里面没有写 "strict": true（严格模式）。这是因为从 TypeScript 6 开始，严格模式默认就是开着的：参数不写类型会报错，可能为 null 的值不处理会报错。今天你看到的大部分报错，都来自严格模式，它们正是你想要的保护。
最后，package.json 里的 build 脚本会从 vite build 改成 tsc && vite build。&& 在终端里的意思是“前一个命令成功了，才运行后一个”：先做类型检查，通过了才打包。
确认 quiz 的工作区是干净的
cd ~/code/quiz
git status如果有没提交的改动，先 commit。迁移过程中改乱了，随时可以用 Git 回到这个起点。
生成一个参考模板
cd ~/code
npm create vite@latest ts-template -- --template vanilla-ts如果问 Install with npm and start now?，选 No。这个项目只用来参考，不需要安装依赖。用 VS Code 打开 ~/code/ts-template/package.json 和 tsconfig.json，对照上午第 7 节看一遍。
把官方 tsconfig.json 复制进 quiz
cp ~/code/ts-template/tsconfig.json ~/code/quiz/~/code/quiz/tsconfig.json 存在，内容和模板里的一模一样，里面有 "types": ["vite/client"] 和 "include": ["src"]。改 package.json，安装 TypeScript
打开参考模板的 package.json，找到 devDependencies 里 "typescript" 那一行，原样复制到 quiz 的 package.json 里。再把 quiz 的 build 脚本改成和模板一样。改完大致是这样（版本号以你的模板为准，不要照抄这里的数字）：
quiz/package.json
{
"name": "quiz",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"preview": "vite preview"
},
"devDependencies": {
"typescript": "~6.0.2",
"vite": "^8.3.0"
}
}注意 JSON 的逗号：typescript 那一行后面要有逗号，最后一项 vite 后面不能有。版本号前的 ~ 比 ^ 更保守，只接受最后一位的小更新。然后安装：
cd ~/code/quiz
npm install
npx tsc -vnpx tsc -v 打印出版本号，和你复制的那一行对得上。把 5 个 .js 文件改成 .ts
用 git mv 改名，Git 会记住“这是同一个文件改了名”，历史不会断：
cd ~/code/quiz
git mv src/main.js src/main.ts
git mv src/questions.js src/questions.ts
git mv src/results.js src/results.ts
git mv src/score.js src/score.ts
git mv src/dom.js src/dom.ts然后改两处引用。第一，index.html 最后的 script 标签改成 src="/src/main.ts"。第二，main.ts 顶部的 import，把 .js 全部改成 .ts：
quiz/src/main.ts
import "./style.css";
import { questions } from "./questions.ts";
import { results } from "./results.ts";
import { pickWorld } from "./score.ts";
import { createText } from "./dom.ts";重启开发服务器（Ctrl + C 后 npm run dev）。
让 tsc 列出所有类型错误
另开一个终端标签页运行：
cd ~/code/quiz
npx tsc你会看到一串报错，每条的格式是“文件名:行:列 - error 编号: 说明”，最后一行告诉你一共几个错误。同时 VS Code 里对应的文件名会变红。你大概会看到这几类：
dom.ts：Parameter 'tag' implicitly has an 'any' type. 参数没写类型。main.ts：'app' is possibly 'null'. 可能为 null。main.ts：Variable 'answers' implicitly has type 'any[]'。空数组推断不出类型。main.ts：Parameter 'world' implicitly has an 'any' type.score.ts：Parameter 'answers' implicitly has an 'any' type.别被数量吓到，很多错误是同一个原因引起的。原则是从上往下、一个文件一个文件地修，每修完一处保存，再运行一次 npx tsc 看剩多少。修的时候先自己看报错说明想办法，想不出来再看下面几步的参考。
修 dom.ts
给三个参数和返回值加上类型，改成上午第 5 节的样子。保存后再运行 npx tsc。
Property 'type' does not exist on type 'HTMLElement'.。这是上午第 5 节预告过的：createText 现在明确返回笼统的 HTMLElement，TS 不认为它是按钮。修 score.ts 和 results.ts
score.ts 里给 answers 参数和计票板加上类型：
quiz/src/score.ts
export function countScores(answers: string[]): { [world: string]: number } {
const scores: { [world: string]: number } = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((world) => {
scores[world] += 1;
});
return scores;
}
export function pickWorld(answers: string[]) {
// 函数体和昨天完全一样，不用改
}注意第二个函数只改了第一行的参数，函数体保留你原来的代码，这里为了省篇幅没有重复写出。把鼠标停在 pickWorld 上，看看 TS 推断出的返回类型。
results.ts 需要告诉 TS“这个对象的键是任意字符串，每个值都有这六个字符串属性”，否则 main.ts 里的 results[world] 会报错。只改第一行，对象内容不动：
quiz/src/results.ts
export const results: {
[world: string]: {
label: string;
name: string;
feeling: string;
summary: string;
detail: string;
recommend: string;
};
} = {
gentleman: {
// 内容和昨天一样
},
// street、thai 同样不变
};这个类型写得又长又挤，你大概会觉得不好看。确实如此，明天会用 interface 给它起个名字，一行搞定。
修 main.ts
main.ts 的改动最多。先自己试着修，修完再对照下面的完整版本。和昨天相比，改动集中在四处：用 getApp 处理 null；answers 标上 string[]；函数参数和返回值加类型；两个按钮改用 document.createElement("button")。
quiz/src/main.ts
import "./style.css";
import { questions } from "./questions.ts";
import { results } from "./results.ts";
import { pickWorld } from "./score.ts";
import { createText } from "./dom.ts";
function getApp(): HTMLDivElement {
const element = document.querySelector<HTMLDivElement>("#app");
if (!element) {
throw new Error("页面里找不到 #app，检查 index.html");
}
return element;
}
const app = getApp();
let currentIndex = 0;
let answers: string[] = [];
function renderQuestion(): void {
const question = questions[currentIndex];
app.innerHTML = "";
const progress = createText("p", "progress", `第 ${currentIndex + 1} 题 / 共 ${questions.length} 题`);
const title = createText("h2", "question", question.text);
const optionList = document.createElement("div");
optionList.className = "options";
question.options.forEach((option) => {
const button = document.createElement("button");
button.type = "button";
button.className = "option";
button.textContent = option.text;
button.addEventListener("click", () => {
chooseOption(option.world);
});
optionList.append(button);
});
app.append(progress, title, optionList);
}
function chooseOption(world: string): void {
answers.push(world);
currentIndex += 1;
if (currentIndex < questions.length) {
renderQuestion();
} else {
renderResult();
}
}
function renderResult(): void {
const { world, topWorlds } = pickWorld(answers);
const result = results[world];
app.innerHTML = "";
const card = document.createElement("section");
card.className = `result-card card-${world}`;
card.append(
createText("p", "card-brand", "三岁的东哥 · 测试结果"),
createText("p", "card-label", "你最需要的是"),
createText("h2", "card-title", result.name),
createText("p", "card-feeling", `他给你的是：${result.feeling}`),
createText("p", "card-summary", result.summary),
createText("p", "card-detail", result.detail),
createText("p", "card-footer", "小红书 / TikTok 搜：三岁的东哥")
);
app.append(card);
if (topWorlds.length > 1) {
const names = topWorlds.map((item) => results[item].label).join("、");
app.append(
createText("p", "tie-note", `你在${names}之间打了个平手，按你最后的选择，结果算作${result.label}。`)
);
}
app.append(createText("p", "recommend", result.recommend));
app.append(createText("p", "share-hint", "截图这张卡片，发给也在看东哥的朋友。"));
const restartButton = document.createElement("button");
restartButton.type = "button";
restartButton.className = "restart";
restartButton.textContent = "再测一次";
restartButton.addEventListener("click", restart);
app.append(restartButton);
}
function restart(): void {
currentIndex = 0;
answers = [];
renderQuestion();
}
renderQuestion();questions.ts 通常不需要改：它是一个写死的数组，TS 能自己推断出每道题的结构。把鼠标停在 questions 上看看推断结果。
确认零错误，并跑一次完整构建
cd ~/code/quiz
npx tsc
npm run buildnpx tsc 什么都不输出，这就代表零错误。npm run build 先安静地通过类型检查，再打印 vite build 的结果。开发服务器里把小游戏完整玩一遍，包括同分和“再测一次”，一切和昨天一样。再做一个小实验：在 questions.ts 里随便找一个选项，把 world 改成 "gentlemen"，运行 npx tsc。你会发现没有报错。今天的类型只规定了“world 是字符串”，拼错的字符串也是字符串。记住这个遗憾，明天解决。改回来。
请 Claude 审稿
在 Claude Code 里打开 quiz 项目，把本页“问 Claude”里的第一条提示词发给它。它会列出审查意见。逐条读，对每一条做出判断：同意就自己动手改，不同意就在笔记里写下理由。不要让它直接改文件。
提交、上线、清理参考模板
cd ~/code/quiz
git add .
git commit -m "测试小游戏迁移到 TypeScript"
git push到 Vercel 的 Deployments 页面看这次的构建日志，会多出一步 tsc 的检查。部署完成后在手机上玩一遍。最后在 Finder 里把 ~/code/ts-template 文件夹拖进废纸篓，它的使命完成了。
/src/main.ts。npx tsc 看完整错误清单，逐个修。TypeScript 是在写代码时报错，还是在用户打开网页时报错？这对你有什么好处？
在写代码时报错。VS Code 在我敲代码的同时检查类型，npx tsc 和 npm run build 会在打包前检查整个项目。用户打开网页时运行的是已经擦掉类型的普通 JavaScript，TypeScript 在那时已经不存在了。好处是：参数传错、可能为 null 的值没处理、属性名写错这类错误，在我写的时候就被标出来，而不是等某位访客点到某个特定的按钮时页面才崩溃；而且 Vercel 部署时运行 npm run build，有类型错误就部署失败，错误到不了线上。
document.querySelector("#app") 在 TypeScript 里的类型为什么是 Element | null？你是怎么处理的？为什么不直接在后面加一个 !？
因为选择器可能找不到元素，这时它返回 null。TS 如实地把这种可能写进类型里，逼我处理。我写了一个 getApp 函数：找不到就 throw 一个写清原因的错误，找到了才返回，返回类型是不带 null 的 HTMLDivElement，这样整个文件里用 app 都不会再报错。加 ! 只是告诉 TS“相信我不会是 null”，报错消失了，但问题没有处理，真出现 null 时页面照样崩，而且错误信息看不出原因。
今天迁移完成后，把某个选项的 world 故意写成 "gentlemen"，npx tsc 没有报错。为什么？
因为今天给 world 定的类型是 string，results 和 scores 用的是 [world: string] 索引签名，意思是任何字符串都可以。"gentlemen" 也是一个字符串，完全符合类型，所以 TS 不会报错。要让 TS 发现这种拼写错误，需要把类型收紧到“只能是 gentleman、street、thai 这三个值之一”，这就是明天要学的字面量类型和联合类型。
type 和 interface 给类型起名字，并说出这门课里两者的分工。World，让“世界只能是 gentleman、street、thai 之一”，拼错时编辑器立刻报错。Array<T>、Record<K, V> 这样的泛型写法，并自己写一个简单的泛型函数。types.ts，为 Look、Platform、QuizQuestion 等定义类型，并让所有数据文件用上它们。昨天迁移到 TypeScript 以后，你做了一个实验：把某个选项的 world 故意写成 "gentlemen"，npx tsc 却没有报错。原因是昨天给 world 定的类型是 string，而拼错的单词也是字符串。昨天的 results.ts 顶部那一大段挤在一起的类型，你大概也觉得难看。
今天要解决这两个问题：一是把类型收紧，让 TS 知道 world 只可能是三个值中的一个；二是给常用的类型起名字，写一次，到处用。学完之后，你的 quiz 项目会有一个 types.ts 文件，它就像整个项目的数据字典：翻开它，就知道这个项目里有哪些数据、每种数据长什么样。
昨天 results.ts 里写的是一个“匿名”的对象类型，想在别的文件里再用一次，只能整段复制。更好的办法是给它起个名字。TypeScript 有两种写法。
第一种是 type，叫类型别名，意思是“给一个类型起个外号”：
type WorldResult = {
label: string;
name: string;
feeling: string;
summary: string;
detail: string;
recommend: string;
};第二种是 interface，叫接口，专门用来描述对象的结构：
interface WorldResult {
label: string;
name: string;
feeling: string;
summary: string;
detail: string;
recommend: string;
}两种写法描述的是同一个东西：一个有六个字符串属性的对象。注意写法上的小差别：type 后面有等号，结尾有分号；interface 没有等号，直接跟花括号。区别在细节上：interface 只能描述对象；type 什么都能起名，包括下一节要讲的联合类型。对你现阶段来说，两者在描述对象时几乎可以互换。
interface 还可以用 extends 在另一个接口的基础上扩展。比如 DAY 49 穿搭会支持上传照片，到时候可以这样写：
interface LookWithPhoto extends Look {
imageUrl: string;
}意思是“LookWithPhoto 拥有 Look 的全部属性，再多一个 imageUrl”。不用把 Look 的属性抄一遍，Look 改了它也跟着变。type 也能做到类似的事，只是写法不同，今天不展开。
既然差不多，就需要一条规则，保证整个项目写法统一。这门课的约定是：
起了名字的类型可以像普通变量一样 export，在别的文件里 import 使用。类型名习惯用大写字母开头，一眼就能和普通变量区分开。
昨天的提示里提过：鼠标停在 const nickname = "小林" 上，类型显示的是 "小林" 而不是 string。在 TypeScript 里，一个具体的值本身也可以当类型用，叫字面量类型。类型 "gentleman" 的意思是：只能是 "gentleman" 这一个字符串，别的都不行。
单独一个字面量类型用处不大，把几个用竖线连起来就厉害了。竖线读作“或者”，这种类型叫联合类型，你昨天在 Element | null 里已经见过：
quiz/src/types.ts
export type World = "gentleman" | "street" | "thai";这一行定义了一个叫 World 的类型：它只能是 gentleman、street、thai 三者之一。把选项的 world 标成这个类型之后：
const option: { text: string; world: World } = {
text: "穿着马甲打斯诺克，一杆清台",
world: "gentlemen",
};
// 报错：Type '"gentlemen"' is not assignable to type 'World'.拼写错误在你敲下的那一刻就被标红，不用等到访客答完 6 题才在结果页崩溃。更贴心的是，你在引号里刚打出一个 g，VS Code 就会弹出三个候选值让你选，根本没机会拼错。
联合类型防住的不只是拼写错误。它还防住了“传错东西”：一个要求 World 的函数，你不可能不小心传进去一个平台名或者一个空字符串。它也让代码自带说明：别人看到参数类型是 World，就知道这里只接受三个世界，不用去翻文档。
enum（枚举）来表示这种“几个固定值之一”。Vite 模板的 tsconfig 开了 erasableSyntaxOnly，这个项目不允许用 enum，统一用字面量联合类型，效果一样而且更简单。以后数据库里的 World 会是一张表，它的 slug 字段存的正是这三个值。定义了联合类型之后，拿到一个这种类型的值，常常要根据它具体是哪一个来做不同的事。比如写一个函数，根据世界返回一句按钮文案：
function buttonText(world: World): string {
switch (world) {
case "gentleman":
return "去看斯诺克";
case "street":
return "去看 BMX";
case "thai":
return "去看泰拳训练";
}
}这是 DAY 14 学过的 switch。有了 World 类型，TS 会帮你做两件事。第一，你在 case 后面打引号时，它会列出三个候选值；如果写了 case "gentlemen":，它会报错说这个值和 World 没有交集，永远不会匹配。第二，它知道三个 case 已经覆盖了所有可能，所以不会抱怨“函数可能没有返回值”。假如你删掉 thai 那个 case，TS 马上报错：函数的返回类型是 string，但有一种情况什么都没返回。将来要是加第四个世界，所有漏处理它的 switch 都会被找出来。
用 if 判断也一样，TS 会跟着你的判断收窄类型：
function describe(world: World): string {
if (world === "street") {
return "街头：BMX 和滑板";
}
// 走到这里，TS 知道 world 只剩 "gentleman" | "thai"
return world === "gentleman" ? "绅士：斯诺克" : "泰风：泰拳";
}把鼠标停在注释下面那行的 world 上，会看到类型已经从三个值缩小成两个。你昨天处理 null 用的就是同一个机制：Element | null 经过 if (!element) 判断后，只剩 Element。联合类型加上判断收窄，是 TypeScript 里最常用的一对组合，React 和 Next.js 的代码里到处都是。
不是每个属性都必须有。比如一套穿搭，除了名字、世界、颜色之外，有的有一句说明（“打斯诺克时穿的那套”），有的没有。在属性名后面加一个问号，表示它是可选属性：
quiz/src/types.ts
export interface Look {
id: number;
name: string;
world: World;
color: string;
note?: string;
}note?: string 的意思是：note 可以写，也可以不写；写了就必须是字符串。
可选意味着读的时候可能读到 undefined，所以 TS 会把 look.note 的类型当成 string | undefined，又是一个联合类型。用之前要先判断：
const lookText = look.note ? `${look.name}：${look.note}` : look.name;这是 DAY 14 学的三元运算符：有 note 就显示“名字：说明”，没有就只显示名字。判断之后，问号左边的分支里 TS 知道 note 一定是字符串，这就是昨天学的类型收窄。
什么时候该用可选属性？只有当“没有”是一种正常情况时。穿搭说明可有可无，所以可选；穿搭名字每套都必须有，就不能加问号。别为了让报错消失而随手加问号，那会把检查一起关掉。
你其实已经用过好几次泛型了，只是没叫它的名字：
string[] 还有一种写法是 Array<string>，意思是“装着字符串的数组”。换成 Array<Look> 就是“装着穿搭的数组”。querySelector<HTMLDivElement>("#app")，尖括号告诉它“找到的会是 div”。泛型就是“带参数的类型”。函数有参数，调用时传进不同的值；泛型有类型参数，使用时传进不同的类型，写在尖括号里。Array 就像一个通用的收纳盒模板，尖括号里填什么，它就变成装什么的盒子。
TypeScript 内置了一个今天就要用的泛型：Record<K, V>，意思是“一个对象，每个 K 都对应一个 V”。
type Scores = Record<World, number>;
// 等于 { gentleman: number; street: number; thai: number }
const results: Record<World, WorldResult> = { ... };把它和昨天的索引签名 { [world: string]: number } 比一比：索引签名允许任何字符串当键，多一个、少一个、拼错一个都不管；Record<World, number> 要求三个世界一个都不能少，也不能多。你在 results.ts 里要是忘了写泰风那一段，TS 会直接告诉你缺了 thai。
你也可以自己写泛型函数。比如结果页想从当前世界的几套穿搭里随机推荐一套：
quiz/src/utils.ts
export function pickRandom<T>(items: T[]): T | undefined {
if (items.length === 0) {
return undefined;
}
const index = Math.floor(Math.random() * items.length);
return items[index];
}<T> 声明一个类型参数，T 是习惯用的名字（Type 的首字母），它代表“调用时才确定的某个类型”。items: T[]：参数是一个装着 T 的数组。T | undefined：返回其中一个 T，数组为空时返回 undefined。Look[]，返回类型就是 Look | undefined；传 Platform[]，返回的就是 Platform | undefined。如果不用泛型，把参数写成 any[] 也能运行，但返回值就成了 any，TS 不再知道你拿到的是一套穿搭，后面写 look.nmae 这种拼写错误也不会报错。泛型的价值就在这里：一个函数适用于各种类型，同时不丢掉类型信息。
今天对泛型的要求只有两条：能读懂别人写的 Array<T>、Record<K, V>，能写出 pickRandom 这种简单的泛型函数。更复杂的用法以后遇到再学。
项目里用到的类型，集中放在 src/types.ts 一个文件里，各个文件按需导入。导入类型时要多写一个 type：
import type { QuizQuestion } from "./types.ts";为什么要加 type？类型只在写代码和检查时存在，Vite 打包时会把它们全部擦掉。import type 明确告诉工具“这一行只导入类型，打包时整行删掉就行”。Vite 模板的 tsconfig 开了 verbatimModuleSyntax，要求导入类型时必须这样写，漏了会报错。假如某个文件同时导出了普通的值和类型，也可以在同一行里只给类型加：import { looks, type Look } from "..."。这门课为了清楚，类型统一放在 types.ts，和值分两行导入。
今天要定义的类型一共有这些：
| 类型 | 用 type 还是 interface | 描述什么 |
|---|---|---|
| World | type（联合类型） | 三个世界之一 |
| QuizOption | interface | 一个选项：文字和对应的世界 |
| QuizQuestion | interface | 一道题：编号、题干、选项数组 |
| WorldResult | interface | 一个世界的结果文案 |
| Scores | type（Record） | 三个世界各几票 |
| QuizOutcome | interface | pickWorld 的返回值 |
| PlatformName | type（联合类型） | 四个平台名之一 |
| Platform | interface | 一个平台：名称、链接、颜色 |
| Look | interface | 一套穿搭，带可选的说明 |
PlatformName 也用了联合类型："小红书" | "TikTok" | "Facebook" | "Instagram"。这样平台列表里只能出现你真正运营的四个平台，把 TikTok 错写成 Tiktok 也会被拦下。Look 和 Platform 今天在 quiz 的结果页用上。之后的 React 项目里，你还会为穿搭、平台、世界定义类似的类型，今天练熟的写法到时直接用得上。
写类型的顺序也有讲究：先写最基础的 World，再写用到它的 QuizOption，再写用到 QuizOption 的 QuizQuestion，像搭积木一样从下往上。以后项目变大，你想了解一个陌生的功能，第一步不是去读几百行逻辑代码，而是先打开 types.ts，看看它处理的数据长什么样。DAY 42 学 Prisma 时，数据库的结构也会写在一个类似的文件里，思路完全一样。
新建 types.ts
在 ~/code/quiz/src 里新建 types.ts。先对照上午第 6 节的表格自己写一遍，再和下面对照：
quiz/src/types.ts
export type World = "gentleman" | "street" | "thai";
export interface QuizOption {
text: string;
world: World;
}
export interface QuizQuestion {
id: number;
text: string;
options: QuizOption[];
}
export interface WorldResult {
label: string;
name: string;
feeling: string;
summary: string;
detail: string;
recommend: string;
}
export type Scores = Record<World, number>;
export interface QuizOutcome {
world: World;
topWorlds: World[];
scores: Scores;
}
export type PlatformName = "小红书" | "TikTok" | "Facebook" | "Instagram";
export interface Platform {
name: PlatformName;
url: string;
color: string;
}
export interface Look {
id: number;
name: string;
world: World;
color: string;
note?: string;
}注意 QuizQuestion 的 options 用的是 QuizOption[]：类型可以互相组合，一个类型里用另一个类型。
给 questions.ts 和 results.ts 用上类型
questions.ts 只在顶部加一行导入，并给数组标上类型：
quiz/src/questions.ts
import type { QuizQuestion } from "./types.ts";
export const questions: QuizQuestion[] = [
// 6 道题的内容不变
];results.ts 把昨天那一大段索引签名，换成一行 Record：
quiz/src/results.ts
import type { World, WorldResult } from "./types.ts";
export const results: Record<World, WorldResult> = {
// gentleman、street、thai 三段内容不变
};npx tsc，这两个文件没有报错。如果报 must be imported using a type-only import，是 import 后面漏了 type。亲手验证 TS 能拦住哪些错误
每做一个实验，看 VS Code 的红线和 npx tsc 的报错，然后撤销（Cmd + Z）：
"gentleman" 改成 "gentlemen"。text 属性。thai 那一段删掉。emoji: "x"。改写 score.ts，体会 Object.keys 的问题
先只改函数签名：参数换成 World[]，countScores 返回 Scores，pickWorld 返回 QuizOutcome，计票板标成 Scores。顶部加上 import type { QuizOutcome, Scores, World } from "./types.ts";。保存后运行 npx tsc。
Type 'string' is not assignable to type 'World' 的报错，指向 pickWorld 里的 return。原因是 Object.keys(scores) 的返回类型永远是 string[]，TS 不认为它一定是三个世界。于是 topWorlds 是 string[]，返回时和 QuizOutcome 要求的 World 对不上。解决办法：自己准备一个类型明确的世界列表，用它代替 Object.keys。完整的 score.ts：
quiz/src/score.ts
import type { QuizOutcome, Scores, World } from "./types.ts";
const WORLDS: World[] = ["gentleman", "street", "thai"];
export function countScores(answers: World[]): Scores {
const scores: Scores = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((world) => {
scores[world] += 1;
});
return scores;
}
export function pickWorld(answers: World[]): QuizOutcome {
const scores = countScores(answers);
const maxScore = Math.max(...Object.values(scores));
const topWorlds = WORLDS.filter((world) => scores[world] === maxScore);
if (topWorlds.length === 1) {
return { world: topWorlds[0], topWorlds, scores };
}
// 同分：从最后一题往前找，第一个属于同分世界的选择就是结果
for (let i = answers.length - 1; i >= 0; i -= 1) {
const answer = answers[i];
if (topWorlds.includes(answer)) {
return { world: answer, topWorlds, scores };
}
}
return { world: topWorlds[0], topWorlds, scores };
}WORLDS.filter(...) 返回的是 World[]，因为从一个 World 数组里筛选，剩下的当然还是 World。Object.values 返回数字数组，本来就没问题，保留不动。
更新 main.ts 的类型
在 main.ts 的 import 区域最后加一行 import type { World } from "./types.ts";，然后把 let answers: string[] = []; 改成 let answers: World[] = [];，把 chooseOption(world: string) 改成 chooseOption(world: World)。
npx tsc 零错误。把鼠标停在 renderResult 里的 world 上，类型显示 World；停在 result 上，显示 WorldResult。加上穿搭和平台数据
新建两个数据文件。平台链接记得换成你自己的主页。
quiz/src/looks.ts
import type { Look } from "./types.ts";
export const looks: Look[] = [
{ id: 1, name: "马甲三件套", world: "gentleman", color: "#2f3e46", note: "打斯诺克时穿的那套" },
{ id: 2, name: "白衬衫配牛津皮鞋", world: "gentleman", color: "#c9b99a" },
{ id: 3, name: "Baggy 裤配 Vans", world: "street", color: "#3a5a80", note: "骑 BMX 不怕蹭脏" },
{ id: 4, name: "Oversize 卫衣", world: "street", color: "#e07a5f" },
{ id: 5, name: "泰拳短裤训练装", world: "thai", color: "#b5171f", note: "每周三次训练的标配" },
{ id: 6, name: "绑手带配运动背心", world: "thai", color: "#f2a541" },
];quiz/src/platforms.ts
import type { Platform } from "./types.ts";
export const platforms: Platform[] = [
{ name: "小红书", url: "https://example.com/xiaohongshu", color: "#ff2442" },
{ name: "TikTok", url: "https://example.com/tiktok", color: "#111111" },
{ name: "Facebook", url: "https://example.com/facebook", color: "#1877f2" },
{ name: "Instagram", url: "https://example.com/instagram", color: "#e1306c" },
];looks 里有的带 note，有的不带，这就是可选属性的用武之地。每套穿搭加了一个 id，明天 React 渲染列表时要用到唯一的编号。试着把 platforms 里的 "TikTok" 改成 "Tiktok"，看 PlatformName 怎么拦住它，再改回来。
写泛型函数 pickRandom
新建 src/utils.ts，写入上午第 5 节的 pickRandom。
在结果页推荐一套穿搭，并列出平台链接
在 main.ts 的 import 区域加上三行：
quiz/src/main.ts
import { looks } from "./looks.ts";
import { platforms } from "./platforms.ts";
import { pickRandom } from "./utils.ts";然后在 renderResult 里，app.append(createText("p", "recommend", result.recommend)); 这一行的下面，加上：
quiz/src/main.ts
const look = pickRandom(looks.filter((item) => item.world === world));
if (look) {
const lookText = look.note ? `${look.name}：${look.note}` : look.name;
app.append(createText("p", "recommend", `今天的穿搭推荐：${lookText}`));
}
const platformList = document.createElement("div");
platformList.className = "platform-links";
platforms.forEach((platform) => {
const link = document.createElement("a");
link.className = "platform-link";
link.href = platform.url;
link.target = "_blank";
link.rel = "noopener";
link.textContent = platform.name;
link.style.borderColor = platform.color;
platformList.append(link);
});
app.append(platformList);逐段看：先用 DAY 16 的 filter 筛出当前世界的穿搭，再交给 pickRandom 随机挑一套。把鼠标停在 look 上，类型是 Look | undefined，所以必须先 if (look) 判断。试着删掉这个 if，看 TS 怎么提醒你。note 是可选的，用三元运算符处理。平台链接的写法和 DAY 22 的 createPlatformButton 一样。
最后在 style.css 末尾加上平台链接的样式：
quiz/src/style.css
/* ===== 平台链接（DAY 26） ===== */
.platform-links {
display: flex;
flex-wrap: wrap;
justify-content: center;
gap: 8px;
max-width: 360px;
margin: 16px auto 0;
}
.platform-link {
padding: 8px 14px;
border: 1px solid #d6d0c4;
border-radius: 999px;
color: inherit;
font-size: 0.875rem;
text-decoration: none;
}全面检查一遍
cd ~/code/quiz
npx tsc
npm run build请 Claude 审查 types.ts
把“问 Claude”里的第一条提示词连同你的 types.ts 发给它。重点看它对“哪里该用可选属性、哪里不该”“type 和 interface 是否符合约定”的意见。同样只接受你想明白了的建议，自己动手改。
提交并上线
cd ~/code/quiz
git add .
git commit -m "定义 World、QuizQuestion、Look、Platform 等类型，结果页加穿搭推荐和平台链接"
git pushimport type { World } from "./types.ts"。Object.keys()，或者某个函数参数还写着 string。顺着报错找到这个值是从哪来的，把源头的类型改成 World。type World = "gentleman" | "street" | "thai"。if (look) 再用，不要用 ! 糊过去。interface 和 type 你会怎么选？联合类型帮你防住了什么错误？
描述对象时两者几乎可以互换，区别是 interface 只能描述对象，type 能给任何类型起名字，包括联合类型。我的约定是：描述一个对象长什么样用 interface，比如 QuizQuestion、Look、Platform；联合类型、字面量类型、Record 这类用 type，比如 World、PlatformName、Scores。关键是整个项目保持一致。联合类型帮我防住了拼写和传错值的错误：World 只能是 gentleman、street、thai 之一，把 gentleman 写成 gentlemen 会在编辑器里立刻标红，不会等到访客答完题结果页才崩溃；平台名也只能是我运营的四个平台之一，TikTok 写成 Tiktok 同样会被拦下。
Record<World, WorldResult> 和昨天的 { [world: string]: WorldResult } 相比，好在哪里？
索引签名允许任何字符串当键：少写一个世界、多写一个不存在的世界、键名拼错，TS 都不会报错，读取 results["gentlemen"] 也不报错。Record<World, WorldResult> 要求三个世界的键一个都不能少、也不能多出别的键，而且只能用 World 类型的值去读取，拼错会直接报错。
pickRandom 的返回类型为什么写成 T | undefined？调用 pickRandom(looks) 时 T 是什么？
因为传进来的数组可能是空的，这时没有东西可以返回，只能返回 undefined。把这种可能写进返回类型，调用的人就必须先判断再使用，避免拿 undefined 去读属性。调用 pickRandom(looks) 时，TS 根据 looks 的类型 Look[] 推断出 T 是 Look，所以返回类型是 Look | undefined。
className、用花括号嵌入表达式、用对象写 style。npm create vite@latest 创建 React + TypeScript 项目 ~/code/dongge-react，并说出 index.html、main.tsx、App.tsx 各自的作用。回想一下 DAY 19 到 DAY 26 你是怎么画页面的：造一个元素，设 class，填文字，放进父元素，一张卡片十几行。数据一变，先 innerHTML = "" 清空，再从头画一遍。到了测试小游戏，renderQuestion 和 renderResult 两个函数加起来已经有好几十行 createElement，而且你得时刻记着“现在页面上有什么、该删什么、该加什么”。
这种写法叫“命令式”：你像指挥工人一样，一步一步告诉浏览器怎么做。页面越复杂，指令越多，越容易漏一步。
React 换了一种思路，叫“声明式”：你只描述“在当前数据下，页面应该长什么样”，至于怎么造元素、怎么增删改，React 替你完成。打个比方，命令式像是你自己进厨房，洗菜、切菜、开火、翻炒一步步来；声明式像是在餐厅点菜，你只说“要一份泰式炒河粉，少辣”，后厨怎么做是厨师的事。
React 的另一个核心概念是组件。你可以把页面想成乐高：头像是一块积木，介绍是一块积木，平台按钮是一块积木。每块积木单独做好，然后拼起来。同一块积木可以用很多次，四个平台按钮就是同一块积木拼了四次，只是颜色和文字不同。今天你就要把链接主页拆成三块积木。
从今天到 DAY 36，你都会在同一个 React 项目 ~/code/dongge-react 里工作：先做链接主页组件，再做 React 版测试小游戏，最后做新官网。
在 React 里，组件就是一个普通的 JavaScript 函数，只有两个特别的要求：函数名必须大写字母开头；它返回的是一段描述界面的代码，叫 JSX。
dongge-react/src/components/Intro.tsx
export default function Intro() {
return (
<div className="intro">
<h1>三岁的东哥</h1>
<p>在外面是绅士、拳手、潮男，在你面前三岁。</p>
</div>
);
}export default function Intro()：定义并默认导出一个叫 Intro 的函数组件。DAY 23 说过，React 社区习惯每个组件一个文件，用默认导出。return ( ... )：返回一段 JSX。JSX 跨多行时用圆括号包起来，避免 return 后面换行导致返回 undefined。定义好的组件，在别的组件里像 HTML 标签一样使用：
import Intro from "./components/Intro.tsx";
function App() {
return (
<main>
<Intro />
</main>
);
}<Intro /> 的意思是“在这里放一个 Intro 组件”，React 会调用 Intro 函数，把它返回的界面放到这个位置。这就是为什么组件名必须大写：React 靠首字母区分，小写的 <div> 是普通 HTML 标签，大写的 <Intro> 是你写的组件。写成小写的 <intro />，React 会以为你要一个叫 intro 的 HTML 标签，页面上什么也不会出现。
JSX 是 JavaScript 的语法扩展，让你能在 JS 里直接写类似 HTML 的结构。Vite 会在打包时把它翻译成普通的 JavaScript 函数调用。因为它本质上是 JavaScript，所以有几条和 HTML 不同的规则：
| 规则 | HTML 里 | JSX 里 |
|---|---|---|
| 只能返回一个根元素 | 随便并列 | 多个元素要包在一个父元素里，或者用空标签 <>...</> 包起来 |
| 所有标签必须闭合 | <img src="a.jpg"> | <img src="a.jpg" />，没有内容的标签以 /> 结尾 |
| class 属性 | class="intro" | className="intro"，因为 class 是 JavaScript 的保留字 |
| label 的 for 属性 | for="nickname" | htmlFor="nickname"，for 也是保留字 |
| 多个单词的属性 | tabindex | 驼峰写法 tabIndex；但 aria-label、data-world 保持连字符 |
| 行内样式 | style="border-color: red" | style={{ borderColor: "red" }}，是一个对象 |
JSX 最有用的能力是用花括号嵌入 JavaScript 表达式。花括号里可以放变量、计算、函数调用，任何能算出一个值的东西：
const name = "三岁的东哥";
const platformCount = 4;
return (
<div>
<h1>{name}</h1>
<p>在 {platformCount} 个平台更新</p>
<img src={"/avatar.jpg"} alt={`${name}的头像`} />
</div>
);花括号可以出现在两个地方：标签之间当文字内容，比如 {name}；属性的值，比如 alt={...}。属性值是固定字符串时直接用引号，需要计算时用花括号。
再看 style 的写法 style={{ borderColor: color }}，两层花括号不是特殊语法：外层是“这里要嵌入 JS 了”，内层是一个 JavaScript 对象。对象的属性名用驼峰，和 DAY 19 学的 element.style.borderColor 一样。
上面的 Intro 把名字和介绍写死在组件里，只能用在一个地方。平台按钮就不行了：四个按钮结构一样，只是名称、链接、颜色不同。总不能写四个组件。
解决办法是 props（properties 的缩写，属性）。props 之于组件，就像参数之于函数：组件定义好“需要哪些信息”，使用它的地方把具体的值传进来。写法和给 HTML 标签写属性一样：
<PlatformButton name="小红书" url="https://example.com/xiaohongshu" color="#ff2442" />
<PlatformButton name="TikTok" url="https://example.com/tiktok" color="#111111" />组件这一边，用 TypeScript 的 interface 写清楚它接收哪些 props，再在函数参数里用 DAY 17 学的解构取出来：
dongge-react/src/components/Intro.tsx
interface IntroProps {
name: string;
tagline: string;
}
export default function Intro({ name, tagline }: IntroProps) {
return (
<div className="intro">
<h1>{name}</h1>
<p>{tagline}</p>
</div>
);
}interface IntroProps：按 DAY 26 的约定，描述对象结构用 interface。它规定 Intro 需要 name 和 tagline 两个字符串。{ name, tagline }: IntroProps：React 调用组件时，会把所有 props 装进一个对象作为第一个参数传进来。这里直接解构，函数里就能用 name 和 tagline 两个变量。可选的 prop 在 interface 里加问号，再在解构时给一个默认值：
interface AvatarProps {
src: string;
alt: string;
size?: number;
}
export default function Avatar({ src, alt, size = 96 }: AvatarProps) {
return <img className="avatar" src={src} alt={alt} width={size} height={size} />;
}size = 96 表示不传 size 时就用 96。于是 <Avatar src="/avatar.jpg" alt="..." /> 得到 96 像素的头像，<Avatar ... size={120} /> 得到 120 像素的。注意数字要用花括号，写成 size="120" 传进去的是字符串，TS 会报错。
最后记住一条：props 是只读的。组件只能使用 props，不能修改它们，就像你不能改写别人寄给你的快递单。数据由外面决定，组件只负责按数据把界面画出来。需要组件自己记住、自己改变的数据，是 DAY 29 要学的 state。
与此相关的还有一个好习惯：组件函数只做一件事，根据 props 算出界面，不要在里面修改组件外面的变量，也不要在里面发请求、改 localStorage。同样的 props 进去，永远得到同样的界面，这样的组件最好理解，也最好复用。那些“副作用”该放在哪里，DAY 30 学 useEffect 时会讲。
用 Vite 创建的 React + TypeScript 项目，比 quiz 多了几个文件：
dongge-react/
├── index.html 入口页面，只有一个空的 <div id="root">
├── package.json 依赖里多了 react 和 react-dom
├── vite.config.ts Vite 配置，加载了 React 插件
├── tsconfig.json TS 配置的总入口，引用下面两个
├── tsconfig.app.json src 里代码的 TS 配置
├── tsconfig.node.json vite.config.ts 的 TS 配置
├── public/ 原样发布的静态文件，今天放头像
└── src/
├── main.tsx 入口：把 App 挂到 #root 上
├── App.tsx 最外层的组件
├── App.css App 的样式
└── index.css 全局样式和 quiz 比，TypeScript 配置拆成了三个文件：tsconfig.app.json 管 src 里的页面代码，里面多了一项 "jsx": "react-jsx"，让 TS 认识 JSX；tsconfig.node.json 管 vite.config.ts 这种在 Node 里运行的配置文件；tsconfig.json 只是把前两个串起来。你还会看到 package.json 的 build 脚本是 tsc -b && vite build，-b 的意思是按这种“多个配置文件”的方式逐个检查。所以在这个项目里手动检查类型，要运行 npx tsc -b，而不是 quiz 里的 npx tsc。vite.config.ts 里加载的 @vitejs/plugin-react 插件，负责在开发和打包时把 JSX 翻译成浏览器能运行的 JavaScript。这些配置都是模板生成好的，今天只需要看懂，不需要改。
文件扩展名是 .tsx，意思是“TypeScript 加 JSX”。只要文件里写了 JSX，就必须用 .tsx；纯逻辑、纯类型的文件（比如 types.ts）仍然用 .ts。
整个项目是从 main.tsx 启动的：
dongge-react/src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.tsx'
createRoot(document.getElementById('root')!).render(
<StrictMode>
<App />
</StrictMode>,
)createRoot(document.getElementById('root')!)：找到 index.html 里的 #root，把它交给 React 管理。从此这个 div 里面的一切都由 React 来画。.render(<App />)：把 App 组件画进去。App 里面再放 Avatar、Intro、PlatformButton，一层套一层，组成一棵组件树。StrictMode：严格模式，只在开发时生效，帮你提前发现一些潜在问题，页面上看不出区别。你会注意到这里用了 DAY 25 说要慎用的 !。这是模板代码，index.html 和 main.tsx 都是项目里固定不变的文件，#root 一定存在，这种情况下用 ! 是可以接受的。main.tsx 保持模板原样即可，今天不需要改它。另外，模板用的是单引号、不写分号，你自己写的文件用双引号加分号，两种写法都合法，保持每个文件内部一致就好。
组件一层套一层，整个页面就形成了一棵组件树。今天链接主页的组件树是这样的：
App
├── Avatar src、alt 由 App 传入
├── Intro name、tagline 由 App 传入
└── nav
├── PlatformButton 小红书
├── PlatformButton TikTok
├── PlatformButton Facebook
└── PlatformButton Instagram对比 DAY 19 的 DOM 树，你会发现两者很像。区别在于 DOM 树的每个节点是一个 HTML 元素，组件树的每个节点是一块你自己定义的积木，一块积木里面可能包含好几个 HTML 元素。React 会把组件树“展开”成真正的 DOM 树交给浏览器。
在这棵树里，数据的流向是固定的：从父组件流向子组件，通过 props 一层层往下传。App 知道平台的名称和链接，把它们交给 PlatformButton；PlatformButton 只管按拿到的数据画按钮，它不知道也不关心数据是从哪来的。这叫单向数据流。好处是出了问题容易追查：某个按钮的链接不对，一定是它的父组件传错了，顺着树往上找就行。
其实你早就写过类似的东西。DAY 19 的 createLookCard(look)、DAY 22 的 createPlatformButton(platform)，都是“数据进去，界面出来”的函数。React 组件就是这种函数的升级版：参数变成了 props，返回值从手工造好的 DOM 元素变成了 JSX。最大的不同在后面：数据变了以后，你不用再手动清空、重画，React 会自己算出页面上哪里需要改，只改那一小部分。这个能力要等 DAY 29 学了 state 才能真正体会到，今天先记住这个方向。
拿到一个页面，怎么决定拆成哪些组件？一个实用的方法是：
决定哪些 prop 必填、哪些可选，也是设计的一部分。名称和链接每个平台按钮都必须有，所以必填；颜色不是必需的，没传时用一个默认的深色边框就好，所以做成可选 prop 并给默认值，和 Avatar 的 size 一样。这样 PlatformButton 在别的地方复用时，只传名称和链接也能用。你会发现这三个 props 和 DAY 26 在 quiz 里定义的 Platform 类型几乎一样，明天会在这个项目里建一个 types.ts，把平台、穿搭、世界这些数据的类型集中管理起来。
今天 App 里会手写四个 PlatformButton。你大概已经想到：平台数据要是放在一个数组里，用 DAY 16 学的 map 生成按钮岂不更省事？没错，这正是明天的内容：列表渲染，以及 React 要求的 key。
创建 React + TypeScript 项目
cd ~/code
npm create vite@latest dongge-react依次选择：
Select a framework：React。Select a variant：TypeScript。注意不要选 TypeScript + React Compiler，也不要选名字后面带斜箭头的选项（那些会跳转到别的脚手架）。Which linter to use?：选默认的第一项 Oxlint。Install with npm and start now?：选 No。npm create vite@latest dongge-react -- --template react-ts。以上选项名称以你实际看到的为准，Vite 的脚手架更新很快。安装依赖，启动开发服务器
cd ~/code/dongge-react
npm install
npm run dev打开终端显示的地址，通常是 http://localhost:5173/。如果 quiz 的开发服务器还开着，Vite 会自动用 5174，以终端显示为准。
认识项目文件，体验热更新
用 VS Code 打开项目（新开一个终端标签页运行 code ~/code/dongge-react）。依次打开 index.html、src/main.tsx、src/App.tsx，对照上午第 5 节看它们的关系。打开 package.json，在 dependencies 里找到 react 和 react-dom。然后在 App.tsx 里把 Get started 改成 三岁的东哥，保存。
清理模板
删掉 src/assets 整个文件夹；把 src/App.css 的内容全部删空；把 src/App.tsx 替换成一个最小的组件：
dongge-react/src/App.tsx
import "./App.css";
function App() {
return (
<main className="links-page">
<p>链接主页，今天拆成组件。</p>
</main>
);
}
export default App;把 src/index.css 替换成全局基础样式：
dongge-react/src/index.css
* {
box-sizing: border-box;
}
body {
margin: 0;
font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Helvetica Neue", sans-serif;
background: #f4f1ea;
color: #1f2a2e;
}最后把 index.html 里的 lang="en" 改成 lang="zh-CN"，<title> 改成“三岁的东哥”。
放好头像
把链接主页的头像复制到 public 文件夹。DAY 05 起头像一直叫 avatar.jpg，放在 links 根目录；如果你后来改过名字或位置，把命令里的第一个路径换成你实际的文件：
cp ~/code/links/avatar.jpg ~/code/dongge-react/public/avatar.jpg
ls ~/code/dongge-react/publicpublic 里的文件会原样发布到网站根目录，所以在代码里用 /avatar.jpg 就能访问，不要写成 /public/avatar.jpg。
http://localhost:5173/avatar.jpg（端口以你的为准），能直接看到头像。写 Avatar 组件
在 src 里新建 components 文件夹，在里面新建 Avatar.tsx。先不看上午的代码，自己写：它接收 src、alt 和可选的 size，默认 96，返回一个 class 为 avatar 的 img。写完对照上午第 4 节检查。
dongge-react/src/components/Avatar.tsx
interface AvatarProps {
src: string;
alt: string;
size?: number;
}
export default function Avatar({ src, alt, size = 96 }: AvatarProps) {
return <img className="avatar" src={src} alt={alt} width={size} height={size} />;
}写 Intro 组件
在 components 里新建 Intro.tsx，接收 name 和 tagline，渲染一个 h1 和一个 p。代码就是上午第 4 节的 Intro，同样先自己写再对照。
写 PlatformButton 组件
dongge-react/src/components/PlatformButton.tsx
interface PlatformButtonProps {
name: string;
url: string;
color?: string;
}
export default function PlatformButton({ name, url, color = "#1f2a2e" }: PlatformButtonProps) {
return (
<a
className="platform-btn"
href={url}
target="_blank"
rel="noopener"
style={{ borderColor: color }}
>
{name}
</a>
);
}逐行看：interface 规定名称和链接必填、颜色可选；解构时给 color 一个默认的深色；a 标签的 href 用花括号接收 url；style 用对象把边框设成平台色；标签之间的 {name} 是按钮文字。属性太多时像这样一个属性一行，更好读。
在 App 里把三个组件组合起来
dongge-react/src/App.tsx
import Avatar from "./components/Avatar.tsx";
import Intro from "./components/Intro.tsx";
import PlatformButton from "./components/PlatformButton.tsx";
import "./App.css";
function App() {
return (
<main className="links-page">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<nav className="platforms" aria-label="东哥的平台">
<PlatformButton name="小红书" url="https://example.com/xiaohongshu" color="#ff2442" />
<PlatformButton name="TikTok" url="https://example.com/tiktok" color="#111111" />
<PlatformButton name="Facebook" url="https://example.com/facebook" color="#1877f2" />
<PlatformButton name="Instagram" url="https://example.com/instagram" color="#e1306c" />
</nav>
</main>
);
}
export default App;把四个 example.com 换成你真实的主页链接。App 读起来几乎就是页面结构的说明书：一个头像、一段介绍、四个平台按钮。每个组件内部怎么实现，在 App 这一层都不用关心。
加上样式
把下面的样式写进 src/App.css。class 名和链接主页一致，你也可以把 ~/code/links/style.css 里自己喜欢的写法搬过来。
dongge-react/src/App.css
.links-page {
display: flex;
flex-direction: column;
align-items: center;
gap: 16px;
max-width: 480px;
margin: 0 auto;
padding: 48px 16px;
text-align: center;
}
.avatar {
border-radius: 50%;
object-fit: cover;
}
.intro h1 {
margin: 0;
font-size: 1.75rem;
}
.intro p {
margin: 8px 0 0;
color: #555;
}
.platforms {
display: flex;
flex-direction: column;
gap: 12px;
width: 100%;
}
.platform-btn {
display: block;
padding: 14px;
border: 2px solid #1f2a2e;
border-radius: 12px;
background: #fff;
color: inherit;
font-weight: 600;
text-decoration: none;
}object-fit: cover 让头像在正方形里等比例裁切，不会被压扁。平台按钮的边框颜色写的是深色，但每个按钮的 style 属性会用平台色覆盖它，行内样式优先级更高。
故意犯错，看 TypeScript 怎么拦
在 App.tsx 里依次试下面几种写法，每次看完 VS Code 的红线和提示就撤销：
url= 改成 href=。url；再恢复，删掉它的 color。size="120"（带引号）。再改成 size={120} 看头像变大。className 改成 class。<Intro ... /> 改成小写的 <intro ... />。npx tsc -b 也能在终端看到类型错误的完整清单，全部撤销后它什么都不输出。提交，并请 Claude 审稿
cd ~/code/dongge-react
git init
git add .
git commit -m "创建 React 项目，拆出 Avatar、Intro、PlatformButton 组件"先确认 git status 里没有 node_modules。然后把“问 Claude”里的第一条提示词发给 Claude，请它审查三个组件和 App.tsx。按审稿人的方式处理意见：想明白的自己改，不同意的写下理由。今天先不推 GitHub、不部署，DAY 36 新官网完成时一起上线。
<avatar />。组件名和使用时的标签名都必须大写开头。<> 和 </> 包起来。public/avatar.jpg，代码里路径是否写成了 /avatar.jpg。文件名大小写也要一致。style="border-color: red"。JSX 里 style 必须是对象：style={{ borderColor: "red" }}，属性名用驼峰。组件是什么？PlatformButton 为什么要通过 props 接收链接和名称？
组件是一个大写字母开头、返回 JSX 的函数，代表页面上一块可以独立开发、反复使用的界面，像一块乐高积木。组件之间可以嵌套组合，App 里放 Avatar、Intro 和 PlatformButton。PlatformButton 通过 props 接收名称、链接和颜色，是因为四个平台按钮结构完全一样，只有这三样不同。把不同的部分做成 props，一个组件就能用四次；要改按钮的样子只改一个文件；以后平台数据来自数组甚至数据库，也只是换一种方式把 props 传进去。如果把链接写死在组件里，就得写四个几乎一样的组件。
说出 JSX 和 HTML 至少三处不同。
任选三处：JSX 里 class 要写成 className，label 的 for 要写成 htmlFor；所有标签都必须闭合，img 要写成 <img />；一个组件只能返回一个根元素，多个元素要用父元素或 <>...</> 包起来；多单词属性用驼峰，比如 tabIndex；style 是一个对象，写成 style={{ borderColor: color }}；可以用花括号嵌入任意 JavaScript 表达式。
Avatar 的 size 是可选 prop，默认 96。写 <Avatar src="/avatar.jpg" alt="头像" size="120" /> 会怎样？应该怎么写？
TypeScript 会报错：带引号的 "120" 是字符串，而 AvatarProps 里 size 的类型是 number。JSX 里传数字、布尔值、变量、表达式都要用花括号，应该写 size={120}。只有固定的字符串才直接用引号。
map 把平台、三个世界、穿搭数据渲染成一组组件，而不是一个个手写。key，并说清楚用数组下标当 key 会出什么问题。&& 三种方式做条件渲染，并避开页面上冒出一个 0 的坑。children 的 Section 组件，用它给页面分区。昨天你把链接主页拆成了 Avatar、Intro、PlatformButton 三个组件。你的 App.tsx 里是这样一行一行写平台按钮的：
dongge-react/src/App.tsx（昨天的写法）
<PlatformButton name="小红书" url="https://example.com/xiaohongshu" color="#ff2442" />
<PlatformButton name="TikTok" url="https://example.com/tiktok" color="#111111" />
<PlatformButton name="Facebook" url="https://example.com/facebook" color="#1877f2" />
<PlatformButton name="Instagram" url="https://example.com/instagram" color="#e1306c" />四个平台时这样写没问题。但想一想接下来会发生什么：你的穿搭会越拍越多，可能有 30 套；DAY 42 起，穿搭会从数据库里读出来，你写代码的时候根本不知道会有几条。一条一条手写，既累又容易漏。
打个比方：你去奶茶店点单，店员不会为每一位客人重新设计一张杯贴，而是用同一个杯贴模板，把每个人的名字和口味填进去，打印出来贴上。数据是一张清单，组件是模板，React 负责按清单把模板一个个“打印”出来。
你在 DAY 19 做过类似的事：用 JavaScript 遍历 looks 数组，createElement 创建卡片，再 appendChild 插进页面。在 React 里，这件事会简单很多：你只需要把数组“变成”一组 JSX，剩下的交给 React。
你在 DAY 16 学过 map：它遍历数组，把每一项“变成”另一个东西，返回一个同样长度的新数组。比如把数字翻倍，把 look 对象变成标题文字。今天我们让 map 把每一项变成一段 JSX。
dongge-react/src/App.tsx
const platforms = [
{ id: 'xiaohongshu', name: '小红书', url: 'https://example.com/xiaohongshu', color: '#ff2442' },
{ id: 'tiktok', name: 'TikTok', url: 'https://example.com/tiktok', color: '#111111' },
{ id: 'facebook', name: 'Facebook', url: 'https://example.com/facebook', color: '#1877f2' },
{ id: 'instagram', name: 'Instagram', url: 'https://example.com/instagram', color: '#e1306c' },
]
// 在组件的 return 里：
<nav className="platforms" aria-label="东哥的平台">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} color={platform.color} />
))}
</nav>逐行看：
const platforms = [...]：一个对象数组，每个对象是一个平台，有 id、名称、链接和品牌色。这就是 DAY 17 你写过、DAY 26 加上类型的“平台对象数组”，只多了一个 id。{ ... }：在 JSX 里，花括号的意思是“这里放一段 JavaScript 表达式，把它的结果显示出来”。昨天你用它放过 {name}。platforms.map((platform) => (...))：对每个平台执行一次箭头函数，参数 platform 就是当前这一项。key={platform.id}：每一项的“身份证”，下一节专门讲。一个新手最常犯的错，是把圆括号写成了花括号：
// 错误：花括号是“函数体”，里面没有 return，每一项都返回 undefined
{platforms.map((platform) => {
<PlatformButton key={platform.id} name={platform.name} url={platform.url} />
})}
// 正确写法一：圆括号，直接返回
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} />
))}
// 正确写法二：花括号 + return
{platforms.map((platform) => {
return <PlatformButton key={platform.id} name={platform.name} url={platform.url} />
})}第一种写法不会报错，页面上就是什么都没有，所以特别难发现。记住：箭头后面是花括号，就一定要写 return。当你在返回之前还需要先算点什么（比如先拼一个字符串），就用写法二。
你也可以先筛选再渲染，把 DAY 16 学的 filter 和 map 连起来用：
{looks
.filter((look) => look.world === 'street')
.map((look) => (
<LookCard key={look.id} look={look} />
))}这段代码的意思是：先从所有穿搭里挑出“街头”的，再把每一套变成一张卡片。
如果你忘了写 key，浏览器控制台会出现一条警告：Each child in a list should have a unique "key" prop.（列表里的每一项都应该有一个唯一的 key）。为什么 React 这么在意它？
先理解 React 的工作方式：每当数据变化，React 会重新执行组件函数，得到一份“新的界面描述”，然后和上一份比较，只把真正变了的地方更新到页面上。对于列表，它要回答一个问题：新列表里的这一项，是旧列表里的哪一项？
打个比方：班主任记学生，有两种方法。一种按座位号，一种按学号。如果一个新同学插班坐到了第一排第一个，按座位号记，老师会以为“1 号座位的人换了、2 号也换了、3 号也换了”，全班都变了；按学号记，老师一眼就知道“只是多了一个人，其他人只是往后挪了”。key 就是学号。没有 key 时，React 只能按位置（座位号）去对应。
key 的规则有三条：
Math.random() 当 key，它每次都变，React 会以为每一项都是新的，全部推倒重建。<LookCard key={...} /> 上，而不是写在 LookCard 组件内部的 article 上。key 从哪里来？最好的来源是数据本身的 id。你的平台有 id: 'xiaohongshu'，穿搭有 id: 1，三个世界有 slug: 'street'。以后数据来自数据库，每一行都会自带一个 id，直接用它。
那能不能用穿搭的标题当 key？看情况。标题今天不重复，但你哪天拍了两套都叫“白 T 配牛仔裤”，key 就撞了；你把标题改个字，React 又会以为这是一套新穿搭。标题是给人看的，随时可能改；id 是给程序用的，一旦定下就不变。所以 key 的首选永远是 id。只有像平台这种数量固定、名字不会变的小列表，用名称也能接受，但既然已经有 id，就没必要冒这个险。
用数组下标当 key 会有什么问题？下标就是“座位号”。假设每张穿搭卡片上有一个输入框，你在第 1 张“深灰马甲配白衬衫”的输入框里写了“这套适合约会”。然后你在列表最前面插入一套新穿搭：
明天你会学 state，组件内部“记住”的东西（比如点赞数、展开还是收起）也有同样的问题：它们跟着 key 走。key 错了，记忆就会张冠李戴。下标只有在“列表永远不会插入、删除、重新排序”的情况下才勉强安全，所以干脆养成习惯：有 id 用 id，没有 id 就给数据加一个。
props.key 是读不到的。如果组件内部也需要 id，要另外用一个名字传进去，比如 id={platform.id}。页面上经常有“看情况显示”的东西：没有穿搭时显示“还没有穿搭”，有描述时才显示描述，登录了才显示“后台”入口。在 React 里这叫条件渲染：用你在 DAY 14 学的 if、三元运算符、&&，决定返回哪一段 JSX。
方式一：if 提前 return。适合“整个组件要换一种样子”的情况，比如空状态：
dongge-react/src/components/LookList.tsx（片段）
if (looks.length === 0) {
return <p className="empty">这里还没有穿搭，过几天再来看看。</p>
}
return (
<div className="look-list">
{looks.map((look) => (
<LookCard key={look.id} look={look} />
))}
</div>
)函数遇到 return 就结束了。数组为空时，组件直接返回那句提示，后面的列表代码根本不会执行。这种写法最好读，推荐优先使用。
方式二：三元运算符 条件 ? A : B。适合在 JSX 中间二选一：
<p>{looks.length > 0 ? `共 ${looks.length} 套穿搭` : '暂时没有穿搭'}</p>方式三：条件 && A。适合“满足条件就显示，不满足就什么都不显示”：
{look.description && <p>{look.description}</p>}回忆 DAY 14：a && b 在 a 为假时直接得到 a，在 a 为真时得到 b。React 对 false、null、undefined 什么都不显示，所以描述为空字符串时，这一行就消失了。
这里有一个经典的坑：
// 数组为空时，页面上会出现一个 0
{looks.length && <LookList looks={looks} />}
// 正确：条件写成真正的 true / false
{looks.length > 0 && <LookList looks={looks} />}原因是：looks.length 为 0 时，0 && ... 的结果是 0。React 虽然不显示 false，但会老老实实显示数字 0。所以 && 左边最好写成明确的比较。
return null。你的页面会有好几个区块：“三个世界”“最近的穿搭”，以后还有“给东哥留言”。每个区块长得差不多：上面一个标题，下面一些内容，外面留一样的间距。内容却完全不同。
这就像相框：相框只负责边框和挂钩，里面放哪张照片它不关心。在 React 里，放在组件开始标签和结束标签之间的内容，会自动作为一个叫 children 的 prop 传进去。
dongge-react/src/components/Section.tsx
import type { ReactNode } from 'react'
type SectionProps = {
title: string
children: ReactNode
}
export default function Section({ title, children }: SectionProps) {
return (
<section className="section">
<h2>{title}</h2>
{children}
</section>
)
}逐行解释：
import type { ReactNode } from 'react'：ReactNode 是 React 提供的一个类型，意思是“任何 React 能显示的东西”：一段 JSX、一段文字、一个数字、一个数组，甚至 null。前面写 import type，是告诉 TypeScript“我只借用一个类型，不借用代码”。Vite 的 React 模板开启了一个叫 verbatimModuleSyntax 的严格设置，导入类型时必须这样写，否则会报错。type SectionProps：和昨天一样，先定义 props 的类型。title 是字符串，children 是 ReactNode。{children}：把传进来的内容原样放在标题下面。用的时候，就像写普通 HTML 标签一样把内容包起来：
<Section title="最近的穿搭">
<LookList looks={looks} />
</Section>这里 <LookList looks={looks} /> 就是 Section 收到的 children。什么时候用普通 prop，什么时候用 children？一个简单的判断：传的是“数据”（一个标题、一个链接），用普通 prop；传的是“一块界面”，用 children。这种“大组件里套小组件”的写法叫组件组合，是 React 搭页面的基本方式。
现在平台数组写在 App.tsx 里。再加上三个世界、六套穿搭，App.tsx 会变得又长又乱。更好的做法是分工：组件文件只管“怎么显示”，数据文件只管“显示什么”，类型文件规定“数据长什么样”。以后换成数据库，你只需要换掉数据的来源，组件一行都不用动。
DAY 26 你已经学会用 type 定义 Look、Platform，用字面量类型规定世界只能是三个之一。今天把这些类型放进 React 项目：
dongge-react/src/types.ts
export type World = 'gentleman' | 'street' | 'thai'
export type WorldInfo = {
slug: World
name: string
feeling: string
tagline: string
}
export type PlatformName = '小红书' | 'TikTok' | 'Facebook' | 'Instagram'
export type Platform = {
id: string
name: PlatformName
url: string
color: string
}
export type Look = {
id: number
title: string
world: World
description: string
}逐行解释：
World：字面量联合类型，世界只能是这三个字符串之一。如果你在数据里手滑写成 'steet'，编辑器会立刻画红线。WorldInfo：一个世界的完整信息。slug 是给程序看的英文名（以后也会出现在网址里），name 是给人看的中文名，feeling 是这个世界给人的感觉。PlatformName 和 Platform：和 DAY 26 一样，平台名只能是四个之一。多了一个 id 字段，专门给列表当 key 用。Look：DAY 26 在 quiz 项目里，穿搭用的是 name 和 note。从今天起，官网项目里改叫 title（标题）和 description（描述），和 DAY 40 以后数据库里的字段名保持一致，到时候就不用再改名了。export，别的文件才能导入它。数据文件导入类型，给数组标上 Look[]（“由 Look 组成的数组”），TypeScript 就会检查每一项是不是都长对了：少写一个字段、字段名拼错、世界写错，都会报错。这就是你在 DAY 25 体会过的好处：错在你写代码的时候被发现，而不是在粉丝打开网页的时候。
今天下午，你会用这些知识把链接主页改造成“数据驱动”的样子。明天学 state 以后，这些列表就能根据访客的点击动起来了。
打开项目，对齐昨天的三个组件
打开终端，进入项目并启动开发服务器：
cd ~/code/dongge-react
code .
npm run dev浏览器打开终端里显示的地址（通常是 http://localhost:5173）。然后在 VS Code 里确认 src/components/ 下有昨天写的三个组件，props 和昨天一样：Avatar 接收 src、alt 和可选的 size；Intro 接收 name 和 tagline；PlatformButton 接收 name、url 和可选的 color。头像图片在 public/avatar.jpg。今天这三个组件一行都不用改，只改使用它们的方式。
type 定义，字符串用单引号、行尾不加分号，这是 Vite 模板的默认风格。昨天你用的 interface、双引号和分号也完全正确（DAY 26 学过 type 和 interface 在这里效果一样），两种风格混着用不影响运行，保存时 Prettier 还会帮你统一格式。git status 提示 not a git repository），先运行 git init，再 git add . 和 git commit -m "DAY 27 组件"，给今天的改动留一个起点。新建类型文件
在 src/ 下新建 types.ts，内容就是上午第 6 节的完整代码（World、WorldInfo、Platform、Look 四个类型）。保存后不会有任何页面变化，这是正常的：类型只在写代码时起作用。
新建平台数据，并用 map 渲染按钮
新建文件夹 src/data/，在里面新建 platforms.ts：
dongge-react/src/data/platforms.ts
import type { Platform } from '../types'
// 把 url 换成你自己在各平台的主页链接
export const platforms: Platform[] = [
{ id: 'xiaohongshu', name: '小红书', url: 'https://example.com/xiaohongshu', color: '#ff2442' },
{ id: 'tiktok', name: 'TikTok', url: 'https://example.com/tiktok', color: '#111111' },
{ id: 'facebook', name: 'Facebook', url: 'https://example.com/facebook', color: '#1877f2' },
{ id: 'instagram', name: 'Instagram', url: 'https://example.com/instagram', color: '#e1306c' },
]这和 DAY 26 quiz 项目里的 platforms.ts 几乎一样，只是每项多了 id。'../types' 里的 .. 表示“上一级文件夹”：data 文件夹的上一级是 src，types.ts 就在 src 里。记得把四个 example.com 换成你真实的主页链接。
新建三个世界的数据
dongge-react/src/data/worlds.ts
import type { World, WorldInfo } from '../types'
export const worlds: WorldInfo[] = [
{ slug: 'gentleman', name: '绅士', feeling: '安全感', tagline: '斯诺克台边，马甲、衬衫、皮鞋。' },
{ slug: 'street', name: '街头', feeling: '心动', tagline: 'BMX 和滑板，Baggy 裤配 Vans。' },
{ slug: 'thai', name: '泰风', feeling: '被保护感', tagline: '泰拳馆里，一条泰拳短裤。' },
]
export function getWorldName(slug: World): string {
const found = worlds.find((world) => world.slug === slug)
return found ? found.name : slug
}getWorldName 用 DAY 16 学的 find 找到对应的世界，返回中文名，比如传 'thai' 得到 '泰风'。找不到时返回原来的英文，保证总有东西可显示。
新建穿搭数据
dongge-react/src/data/looks.ts
import type { Look } from '../types'
export const looks: Look[] = [
{ id: 1, title: '深灰马甲配白衬衫', world: 'gentleman', description: '打斯诺克那天穿的，袖子挽到小臂。' },
{ id: 2, title: '棕色皮鞋和西裤', world: 'gentleman', description: '鞋头擦过一遍，站在球台边不抢戏。' },
{ id: 3, title: 'Baggy 裤配 Vans', world: 'street', description: '骑 BMX 不卡腿，摔了也不心疼。' },
{ id: 4, title: 'Oversize 白 T', world: 'street', description: '滑板公园的标准装，风一吹就鼓起来。' },
{ id: 5, title: '红色泰拳短裤', world: 'thai', description: '训练完绑带还没拆。' },
{ id: 6, title: '泰式印花衬衫', world: 'thai', description: '打完拳去吃泰餐时换上的那件。' },
]试着把某一项的 world 故意改成 'steet'，看编辑器报什么错，再改回来。文案可以换成你自己真实的穿搭，记住“说事情不说情话”：写你穿它去做了什么，而不是写甜言蜜语。
写 LookCard：一张穿搭卡片
dongge-react/src/components/LookCard.tsx
import type { Look } from '../types'
import { getWorldName } from '../data/worlds'
type LookCardProps = {
look: Look
}
export default function LookCard({ look }: LookCardProps) {
return (
<article className="look-card">
<p className="look-world">{getWorldName(look.world)}</p>
<h3>{look.title}</h3>
<p>{look.description}</p>
</article>
)
}注意这里 props 只有一个 look，整套穿搭作为一个对象传进来，比拆成 title、world、description 三个 props 更省事。
写 LookList：列表加空状态
dongge-react/src/components/LookList.tsx
import type { Look } from '../types'
import LookCard from './LookCard'
type LookListProps = {
looks: Look[]
}
export default function LookList({ looks }: LookListProps) {
if (looks.length === 0) {
return <p className="empty">这里还没有穿搭，过几天再来看看。</p>
}
return (
<div className="look-list">
{looks.map((look) => (
<LookCard key={look.id} look={look} />
))}
</div>
)
}先自己对照上午第 3、4 节检查：key 写在哪里？空状态用的是哪种条件渲染？
写 Section：接收 children 的区块组件
新建 src/components/Section.tsx，内容是上午第 5 节的完整代码。
组装 App.tsx
把 App.tsx 改成下面这样：
dongge-react/src/App.tsx
import Avatar from './components/Avatar'
import Intro from './components/Intro'
import PlatformButton from './components/PlatformButton'
import Section from './components/Section'
import LookList from './components/LookList'
import { platforms } from './data/platforms'
import { worlds } from './data/worlds'
import { looks } from './data/looks'
import './App.css'
export default function App() {
return (
<main className="links-page">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<nav className="platforms" aria-label="东哥的平台">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} color={platform.color} />
))}
</nav>
<Section title="三个世界">
<ul className="world-list">
{worlds.map((world) => (
<li key={world.slug}>
<strong>{world.name}</strong> · {world.feeling}
<p>{world.tagline}</p>
</li>
))}
</ul>
</Section>
<Section title="最近的穿搭">
<LookList looks={looks} />
</Section>
</main>
)
}给列表加一点样式
昨天的 .links-page 是一个 480 像素宽、所有内容居中的窄列，放三列卡片太挤。先打开 src/App.css，把原来的 .links-page 整条规则换成下面这两条：
.links-page {
max-width: 720px;
margin: 0 auto;
padding: 48px 16px;
text-align: center;
}
.links-page .avatar {
display: block;
margin: 0 auto 16px;
}再在 App.css 末尾追加下面的样式（DAY 32 会整体换成 Tailwind，今天先用普通 CSS）：
dongge-react/src/App.css
.platforms {
margin-top: 24px;
}
.section {
margin-top: 40px;
}
.section h2 {
font-size: 1.25rem;
margin-bottom: 16px;
}
.world-list {
list-style: none;
padding: 0;
display: grid;
gap: 12px;
}
.look-list {
display: grid;
gap: 16px;
}
@media (min-width: 768px) {
.world-list,
.look-list {
grid-template-columns: repeat(3, 1fr);
}
}
.look-card {
padding: 16px;
border-radius: 16px;
background: #ffffff;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
text-align: left;
}
.look-world {
font-size: 0.875rem;
color: #8a6d3b;
}
.empty {
padding: 32px;
text-align: center;
border: 1px dashed #bbbbbb;
border-radius: 16px;
}做三个小实验，亲眼看到今天讲的问题
实验一：把 LookList 里的 key={look.id} 删掉，保存，看控制台出现什么警告。看完加回去。
实验二：把 App.tsx 里的 <LookList looks={looks} /> 临时改成 <LookList looks={[]} />，确认看到空状态提示。看完改回去。
实验三：在 App.tsx 的“最近的穿搭”里临时加一行 {[].length && <p>有穿搭</p>}，看页面上是不是冒出一个 0。再改成 {[].length > 0 && <p>有穿搭</p>}，0 消失。看完删掉这一行。
请 Claude 审查，然后提交
从今天到 DAY 36，Claude 的角色是“审稿人”：你先写完，再请它审查。把 LookList.tsx、LookCard.tsx、Section.tsx 的代码发给 Claude（提示词见本页“问 Claude”），读完它的意见，自己动手改。改完提交：
git add .
git commit -m "DAY 28 列表、key、空状态和 Section 组件"明天你会让这些列表“动起来”：点一下按钮，只看某个世界的穿搭。
=> { ... } 改成 => ( ... )，或者在花括号里加上 return。<LookCard key={look.id} ... />），写在 LookCard 组件内部的 article 上是没用的。也检查一下 id 有没有重复。{数组.length && ...}。改成 {数组.length > 0 && ...}。import type { Look } from '../types'，不能写成普通的 import { Look }。src/data/looks.ts，从 components 文件夹出发要先用 .. 回到 src。列表为什么需要 key？用数组下标当 key 会有什么问题？
数据变化后，React 要把新列表和旧列表对比，判断哪一项是新增、哪一项被删除、哪一项只是换了位置，key 就是每一项的身份证。有了稳定唯一的 key，React 能准确地保留、移动或删除对应的组件。用数组下标当 key，相当于按座位号认人：一旦在前面插入、删除或重新排序，所有项的下标都会变，React 会把原来属于 A 的组件和它内部记住的东西（输入框里的文字、state）错配给 B，出现内容张冠李戴，还会多做很多无用的更新。所以应该用数据自己的 id 当 key。
下面这段代码运行后页面上什么都没有，也没有报错。为什么？怎么改？
{looks.map((look) => {
<LookCard key={look.id} look={look} />
})}箭头后面用了花括号，花括号表示函数体，函数体里没有 return，所以每一项都返回 undefined，React 不显示 undefined。改法一：把花括号换成圆括号 (look) => ( <LookCard ... /> )；改法二：保留花括号，在里面写 return <LookCard ... />。
在 <Section title="最近的穿搭"><LookList looks={looks} /></Section> 里，Section 组件是怎么拿到 LookList 的？什么时候用 children，什么时候用普通 prop？
写在组件开始标签和结束标签之间的内容，React 会自动作为名为 children 的 prop 传给组件，Section 在自己的 JSX 里写 {children} 就能把它显示出来，类型用 ReactNode。传的是“数据”（标题、链接、数字）时用普通 prop；传的是“一整块界面”时用 children，这样 Section 只负责外框，里面放什么由使用它的人决定。
useState 给组件加上“记忆”，点击按钮后页面跟着变化。onClick={handleClick} 和 onClick={handleClick()}，并会给处理函数传参数。昨天的页面是“静态”的：数据写死在文件里，打开是什么样就一直是什么样。DAY 20 你用原生 JavaScript 做过风格切换：点按钮，改 body 的 class。今天用 React 的方式重做一遍。你可能会先这样试：
export default function App() {
let theme = 'gentleman'
function handleClick() {
theme = 'street'
console.log(theme)
}
return (
<div className={`app theme-${theme}`}>
<button type="button" onClick={handleClick}>街头</button>
</div>
)
}点按钮后，控制台确实打印了 street，但页面纹丝不动。原因有两个：
App()。函数一开头就是 let theme = 'gentleman'，你刚才的修改被覆盖了。先弄清一个词：渲染。在 React 里，“渲染”指的是 React 调用你的组件函数、拿到它返回的 JSX 的过程。页面第一次打开时渲染一次，之后每当数据变化，React 会再渲染一次，把新旧两份结果对比，只更新真正变了的部分。所以你写的组件函数不是“执行一次就完事”，而是会被反复调用很多次。
打个比方：组件每渲染一次，就像拍一张照片。普通变量是你在照片上用笔改的字，下一次拍照，一切又回到原样。你需要的是一个“照片之外的小本子”：React 替你记住一个值，你改它时 React 会知道，并重新拍一张新照片。这个小本子就是 state（状态）。
DAY 20 的原生写法里，你是“亲手改页面”：找到 body，改它的 class。React 的思路反过来：你只改数据，页面由 React 根据数据重新画出来。你不再需要 querySelector，也不用记得“改了数据还要去改哪几个元素”，这就是 React 最省心的地方。
dongge-react/src/App.tsx（片段）
import { useState } from 'react'
import type { World } from './types'
export default function App() {
const [theme, setTheme] = useState<World>('gentleman')
return (
<div className={`app theme-${theme}`}>
<button type="button" onClick={() => setTheme('street')}>街头</button>
</div>
)
}逐行解释：
import { useState } from 'react'：useState 是 React 提供的一个函数。React 里以 use 开头的函数叫 Hook（钩子），意思是“把组件钩到 React 的某种能力上”。useState 钩上的就是“记忆”。useState<World>('gentleman')：告诉 React“我要一个 state，初始值是 'gentleman'”。尖括号里的 World 是 DAY 26 学的泛型写法，规定这个 state 只能是三个世界之一。const [theme, setTheme] = ...：useState 返回一个只有两项的数组，这里用解构把它们取出来。第一项 theme 是当前的值，第二项 setTheme 是修改它的函数。名字你可以随便起，习惯写成 xxx 和 setXxx。setTheme('street')：调用它时，React 会记下新值，然后重新执行 App。这一次 useState 返回的 theme 就是 'street'，className 变成 app theme-street，页面随之更新。有了 TypeScript，如果你手滑写成 setTheme('steet')，编辑器会马上报错。这是 DAY 26 那个字面量类型在帮你站岗。
你可能会好奇：每次渲染都会执行 useState('gentleman')，为什么不会每次都被重置成 gentleman？因为初始值只在组件第一次渲染时使用。之后再执行到这一行，React 会忽略括号里的初始值，直接把小本子上记着的最新值交给你。
如果 state 本身就是一个字符串、数字这种简单值，TypeScript 可以从初始值推断出类型，比如 useState(0) 自动就是 number，不用写尖括号。只有当你想把类型限定得更窄（只能是三个世界之一），或者初始值是空数组这种看不出类型的值时，才需要写 useState<World>、useState<number[]>([])。
使用 Hook 有两条规则，现在记住就行：
每一个组件实例都有自己独立的 state。页面上有六张 LookCard，如果每张卡片里都有一个 useState(0) 的点赞数，那就是六个互不相干的计数，点这张不会影响那张。
DAY 20 你用 addEventListener('click', handler) 监听点击。在 React 里，直接把函数写在 JSX 属性上：
function handleStreetClick() {
setTheme('street')
}
// 正确：把函数本身交给 React，点击时由 React 调用
<button type="button" onClick={handleStreetClick}>街头</button>
// 错误：加了括号，等于“渲染时立刻调用”，而不是点击时
<button type="button" onClick={handleStreetClick()}>街头</button>第二种写法有多严重？渲染时调用了 setTheme，setTheme 触发重新渲染，重新渲染又调用 setTheme……无限循环。React 会拦下来并报错：Too many re-renders。
那需要传参数怎么办？比如三个按钮共用一个处理函数，只是传的世界不同。答案是再包一层箭头函数：
<button type="button" onClick={() => setTheme('thai')}>泰风</button>() => setTheme('thai') 是一个新函数，React 在点击时调用它，它再去调用 setTheme('thai')。配合昨天学的 map，三个按钮一次写完：
{worlds.map((world) => (
<button key={world.slug} type="button" onClick={() => setTheme(world.slug)}>
{world.name}
</button>
))}几个小习惯：处理函数命名为 handle 开头，比如 handleLike；按钮写上 type="button"，以后放进表单里就不会被误当成“提交”按钮。
和 DAY 20 一样，React 调用处理函数时也会传进一个事件对象，里面有这次点击或输入的信息。需要时在参数里接住它就行，比如 onClick={(event) => console.log(event.target)}。今天的按钮用不到它，明天做表单时会天天用。
还有一点先有个印象：事件处理函数也可以作为 props 传给子组件。比如以后你把风格按钮抽成一个 WorldSwitcher 组件，App 可以把 setTheme 包成一个 onChange 传给它，按钮被点时由子组件调用。这种 props 习惯以 on 开头命名。DAY 31 做测试小游戏时，你会大量用到这个技巧。
state 也可以是对象或数组。比如记录访客的偏好：
const [profile, setProfile] = useState({ nickname: '小鹿', world: 'gentleman' })
// 错误：直接改对象里的字段
profile.world = 'street'
// 正确：做一个新对象交给 set 函数
setProfile({ ...profile, world: 'street' })第一种写法，对象里的值确实变了，但页面不会更新。因为 React 判断“state 有没有变”的方法很简单：新给的值和旧的值是不是同一个东西。你改的是原来那个对象，它还是“同一个东西”，React 认为没变化，什么都不做。更糟的是，没调用 setProfile，React 压根没被通知。
打个比方：你想让朋友换一张头像，要发一张新照片给他，而不是在他手机里那张照片上涂改。第二种写法里，{ ...profile, world: 'street' } 用 DAY 17 学的展开运算符，先把 profile 的所有字段复制过来，再用新的 world 覆盖，得到一个全新的对象。
数组同理，不要用 push、splice 这些会改动原数组的方法，而要生成新数组：
const [likedIds, setLikedIds] = useState<number[]>([])
// 添加：展开旧数组，在后面放新的一项
setLikedIds([...likedIds, 3])
// 删除：用 filter 生成一个不含它的新数组
setLikedIds(likedIds.filter((id) => id !== 3))记住一句话：把 state 当成只读的，要改就给 React 一个新值。
看这段代码，你觉得控制台会打印什么？
function handleClick() {
setTheme('street')
console.log(theme)
}答案是旧值 'gentleman'。原因是：set 函数不会立刻改掉当前这个变量，它只是“预约”下一次渲染用新值。在当前这次渲染里，theme 就是一个普通的常量，它的值在这次渲染开始时就定了，这叫“state 是一张快照”。
为什么要这样设计？想象一下，如果 theme 在函数执行到一半时突然变了，同一个函数里前半段用的是绅士、后半段用的是街头，代码就很难推理。快照保证了：在一次渲染里，你看到的所有 state 都是同一时刻的值，前后一致。想知道新值，就等下一次渲染；或者干脆在调用 set 之前，先把新值存进一个普通常量里，后面的代码用这个常量。
用点餐打比方：你对服务员说“加一份薯条”，服务员记下来，但你桌上的菜不会立刻变多。服务员会等你把这一轮点完，再一次性交给厨房。React 也是这样：一个事件处理函数里的所有 set 调用，会等函数执行完再合并成一次重新渲染。这叫批处理，好处是不会改一次就刷新一次页面。
这会导致一个经典问题：
const [likes, setLikes] = useState(0)
function handleLike() {
setLikes(likes + 1)
setLikes(likes + 1)
setLikes(likes + 1)
}点一次，likes 从 0 变成 1，而不是 3。因为这三行里的 likes 都是快照里的 0，三次都是“请把它设成 1”。如果你确实需要基于上一次的结果连续计算，就传一个更新函数：
function handleLike() {
setLikes((n) => n + 1)
setLikes((n) => n + 1)
setLikes((n) => n + 1)
}(n) => n + 1 的意思是“拿排在前面的最新结果，加 1”。React 会按顺序执行：0 变 1，1 变 2，2 变 3。日常只改一次时，直接写新值就行；新值依赖旧值、并且可能连续改时，用更新函数。
下午你要做“只看某个世界”的筛选。你可能会想用两个 state：一个存当前选了哪个世界，一个存筛选后的穿搭数组。其实第二个完全不需要：
type Filter = World | 'all'
const [filter, setFilter] = useState<Filter>('all')
const visibleLooks = filter === 'all' ? looks : looks.filter((look) => look.world === filter)逐行解释：Filter 是一个联合类型，要么是三个世界之一，要么是 'all'（全部）。state 只存“用户选了什么”。visibleLooks 每次渲染时根据 filter 现算出来：选了全部就用全部穿搭，否则用 filter 筛一遍。用户一点按钮，filter 变了，组件重新执行，visibleLooks 自然就是新的。
如果你把筛选结果也存成 state，就要保证两个 state 永远同步，一不小心就会出现“按钮显示街头，列表却还是全部”的 bug。state 越少越好，能从已有数据算出来的，就当场算。
最后说一个下午你会亲眼看到的现象：state 是跟着组件“在页面上的那个位置”（准确地说，跟着 key）走的。一张卡片被筛选掉、从页面上移除时，它的 state 也一起丢掉了；再切回“全部”，它是一张全新的卡片，state 从初始值重新开始。昨天学的 key，在这里又起作用了。
那 props 和 state 到底什么关系？用一张表对比：
| props | state | |
|---|---|---|
| 从哪来 | 父组件传进来 | 组件自己用 useState 创建 |
| 谁能改 | 只有父组件能改，子组件只读 | 组件自己通过 set 函数改 |
| 像什么 | 函数的参数 | 组件自带的小本子 |
| 今天的例子 | LookList 收到的 looks | App 里的 theme 和 filter |
两者经常接力：父组件的 state，往往会变成子组件的 props。App 里的 visibleLooks 是从 filter 这个 state 算出来的，传给 LookList 时，它就成了 LookList 的 props。LookList 并不知道也不关心这份数据是怎么来的，它只管显示。这样分工，每个组件都很简单。
先亲手验证“普通变量不行”
启动项目（cd ~/code/dongge-react，npm run dev）。在 App.tsx 的组件函数开头临时加上 let test = 0，在 return 的 JSX 里加一个按钮：
<button type="button" onClick={() => { test = test + 1; console.log(test) }}>
普通变量 {test}
</button>点几下，观察控制台的数字在涨，按钮上的数字一直是 0。确认之后把这个按钮和 let test = 0 删掉。
加上风格 state
在 App.tsx 顶部导入 useState 和 World 类型，在组件第一行创建 state，并把最外层改成一个带风格 class 的 div，原来的 main 放进去。完整的 App.tsx 在第 6 步给出，你可以先自己试着写，再对照。
import { useState } from 'react'
import type { World } from './types'
// 组件第一行：
const [theme, setTheme] = useState<World>('gentleman')给三个世界定颜色
在 src/App.css 末尾追加下面的样式。如果你 DAY 09 已经给三个世界定过颜色，把颜色值换成你自己的。
dongge-react/src/App.css
.app {
min-height: 100vh;
background: var(--bg);
color: var(--text);
transition: background 0.3s, color 0.3s;
}
.theme-gentleman {
--bg: #f4f1ea;
--text: #1f1d1a;
--accent: #6b4f2a;
--card: #ffffff;
}
.theme-street {
--bg: #141414;
--text: #f5f5f5;
--accent: #ff5a1f;
--card: #242424;
}
.theme-thai {
--bg: #fff4e0;
--text: #2a1a10;
--accent: #c8102e;
--card: #ffffff;
}
.switcher,
.filters {
display: flex;
flex-wrap: wrap;
justify-content: center;
gap: 8px;
margin: 16px 0;
}
.switcher button,
.filters button {
padding: 8px 16px;
border: 1px solid var(--accent);
border-radius: 999px;
background: transparent;
color: var(--accent);
cursor: pointer;
}
.switcher button.active,
.filters button.active {
background: var(--accent);
color: #ffffff;
}再改 App.css 里已有的几处写死的颜色，让它们跟着风格变：
.look-card：background: #ffffff; 改成 background: var(--card);。.look-world：color: #8a6d3b; 改成 color: var(--accent);。.platform-btn：background: #fff; 改成 background: var(--card);。.intro p：color: #555; 改成 opacity: 0.75;（让它继承文字颜色，只是淡一点）。这样在深色的街头风格下，卡片和按钮不会变成“白底白字”，介绍文字也不会是深灰色压在黑底上看不清。
做风格切换按钮
在 Intro 下面加一排按钮，用 map 生成，当前选中的那个加上 active class：
<div className="switcher">
{worlds.map((world) => (
<button
key={world.slug}
type="button"
className={theme === world.slug ? 'active' : ''}
onClick={() => setTheme(world.slug)}
>
{world.name}
</button>
))}
</div>亲眼看到“快照”
把风格按钮的 onClick 临时改成：
onClick={() => {
setTheme(world.slug)
console.log('点了', world.slug, '当前 theme 是', theme)
}}从绅士点到街头，控制台会打印“点了 street 当前 theme 是 gentleman”。对照上午第 5 节理解为什么，然后把 onClick 改回 () => setTheme(world.slug)。
加上“只看某个世界”的筛选
这是今天 App.tsx 的完整代码。先自己把筛选写出来，再对照：
dongge-react/src/App.tsx
import { useState } from 'react'
import type { World } from './types'
import Avatar from './components/Avatar'
import Intro from './components/Intro'
import PlatformButton from './components/PlatformButton'
import Section from './components/Section'
import LookList from './components/LookList'
import { platforms } from './data/platforms'
import { worlds } from './data/worlds'
import { looks } from './data/looks'
import './App.css'
type Filter = World | 'all'
export default function App() {
const [theme, setTheme] = useState<World>('gentleman')
const [filter, setFilter] = useState<Filter>('all')
const visibleLooks = filter === 'all' ? looks : looks.filter((look) => look.world === filter)
return (
<div className={`app theme-${theme}`}>
<main className="links-page">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<div className="switcher">
{worlds.map((world) => (
<button
key={world.slug}
type="button"
className={theme === world.slug ? 'active' : ''}
onClick={() => setTheme(world.slug)}
>
{world.name}
</button>
))}
</div>
<nav className="platforms" aria-label="东哥的平台">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} color={platform.color} />
))}
</nav>
<Section title="三个世界">
<ul className="world-list">
{worlds.map((world) => (
<li key={world.slug}>
<strong>{world.name}</strong> · {world.feeling}
<p>{world.tagline}</p>
</li>
))}
</ul>
</Section>
<Section title="最近的穿搭">
<div className="filters">
<button
type="button"
className={filter === 'all' ? 'active' : ''}
onClick={() => setFilter('all')}
>
全部
</button>
{worlds.map((world) => (
<button
key={world.slug}
type="button"
className={filter === world.slug ? 'active' : ''}
onClick={() => setFilter(world.slug)}
>
只看{world.name}
</button>
))}
</div>
<LookList looks={visibleLooks} />
</Section>
</main>
</div>
)
}实验：连续 set 三次
在 LookCard.tsx 里临时加一个“喜欢”按钮：顶部加 import { useState } from 'react'，组件里加：
const [likes, setLikes] = useState(0)
function handleLike() {
setLikes(likes + 1)
setLikes(likes + 1)
setLikes(likes + 1)
}在 article 里最后加 <button type="button" onClick={handleLike}>喜欢 {likes}</button>。点一下，看数字是 1 还是 3。再把三行改成 setLikes((n) => n + 1)，再点，看变化。
实验：被筛掉的卡片会忘记自己的 state
保留上一步的喜欢按钮。在“全部”下给“深灰马甲配白衬衫”点几次喜欢，再点“只看街头”，然后点回“全部”。你会发现马甲那张的喜欢数回到了 0，而如果你给街头卡片点过喜欢，它们在切换时一直在页面上，计数还在。对照上午第 6 节最后一段想一想为什么。
实验结束后，把 LookCard 里的喜欢按钮、useState 导入全部删掉，恢复成昨天的样子（喜欢数没有保存到任何地方，留着会误导粉丝）。
请 Claude 审查
把 App.tsx 发给 Claude，请它按“问 Claude”里的第一条提示词审查。重点看它有没有指出多余的 state、错误的事件写法。你自己决定改哪些，自己动手改。
提交
git add .
git commit -m "DAY 29 用 state 做风格切换和世界筛选"profile.world = 'street'）。必须调用 set 函数，并且给它一个新值。onClick={setTheme('street')}，渲染时就调用了。改成 onClick={() => setTheme('street')}。props 和 state 有什么区别？
props 是父组件传给子组件的数据，子组件只能读、不能改，就像函数的参数；state 是组件自己记住的数据，由组件自己通过 set 函数修改，修改后 React 会重新渲染这个组件。两者经常配合：父组件把自己的 state（或由 state 算出来的值）作为 props 传给子组件，比如 App 的 filter 算出 visibleLooks，再作为 props 传给 LookList。判断标准：数据由谁拥有、谁能改。
下面的函数执行一次后，likes 从 0 变成几？为什么？如果想每点一次加 3，应该怎么写？
function handleLike() {
setLikes(likes + 1)
setLikes(likes + 1)
setLikes(likes + 1)
}变成 1。在这一次渲染里 likes 是一张快照，值固定为 0，三行都是“把 likes 设成 0 + 1”。要加 3，可以写成三次 setLikes((n) => n + 1)，更新函数每次拿到的是排在前面的最新结果；或者直接写一次 setLikes(likes + 3)。
今天的筛选功能里，为什么只用了一个 filter 的 state，而没有把筛选后的数组 visibleLooks 也做成 state？
visibleLooks 可以随时由 filter 和 looks 算出来。每次 filter 变化组件都会重新渲染，visibleLooks 会自动重新计算。如果把它也存成 state，就得在每次修改 filter 时同时修改它，一旦忘了就会出现两个 state 不一致的 bug。state 越少越不容易出错。
DAY 21 你用原生 JavaScript 做过“给东哥留言”：监听表单的 submit 事件，调用 preventDefault，再用 document.querySelector('#content').value 把输入框里的字“读出来”。在那种写法里，输入的内容存在浏览器的输入框里，你需要时再去取。
React 推荐反过来：把输入的内容存在 state 里，输入框只是把 state 显示出来。用户每敲一个字，就更新一次 state；state 变了，输入框跟着显示新内容。这样的输入框叫受控组件，因为它的值完全由 React 控制。
打个比方：原生写法像是让顾客自己在纸上写菜单，结账时服务员再去看纸上写了什么；受控写法像是服务员拿着点单机，顾客说一个菜，服务员就录一个，点单机屏幕上显示的永远是系统里记录的内容。点单机的好处是，任何时候都能知道“现在点了什么”，可以实时算总价、实时提醒“这道菜卖完了”。
对应到你的留言表单，受控写法带来三个直接的好处：可以实时显示“已经写了多少字”；可以在用户输入时就提示“超出长度”；提交成功后，把 state 设成空字符串，输入框就清空了，不用去找元素。
dongge-react/src/components/MessageForm.tsx（片段）
const [nickname, setNickname] = useState('')
<label htmlFor="nickname">你的昵称（可以不填）</label>
<input
id="nickname"
value={nickname}
onChange={(event) => setNickname(event.target.value)}
maxLength={20}
/>逐行解释：
useState('')：昵称的 state，初始是空字符串。一定要给空字符串，而不是什么都不写。什么都不写时初始值是 undefined，React 会以为这是一个“不受控”的输入框，之后又变成受控，控制台会出现警告。htmlFor="nickname"：就是 HTML 里 label 的 for 属性。因为 for 在 JavaScript 里是循环的关键字，JSX 里改名叫 htmlFor。同样的道理，class 在 JSX 里叫 className。DAY 05 学过：label 和 input 用 id 关联起来，点文字就能聚焦输入框，读屏软件也能读出这是什么输入框。value={nickname}：输入框显示的内容，永远等于 state。onChange={(event) => setNickname(event.target.value)}：用户每输入或删除一个字，React 都会调用它。event.target 是触发事件的那个输入框，.value 是它现在的内容。我们把这个内容存进 state，state 变了，组件重新渲染，value 就是新内容。maxLength={20}：HTML 自带的长度限制，浏览器最多让你输入 20 个字。JSX 里属性值是数字时用花括号。注意 React 的 onChange 和原生的 change 事件不一样：原生 change 要等输入框失去焦点才触发，React 的 onChange 是每敲一个字就触发一次，相当于原生的 input 事件。
如果你只写了 value 却忘了写 onChange，会发生什么？输入框被“锁死”了：你敲键盘，React 立刻又把它改回 state 里的值，所以怎么都打不进字。控制台也会提醒你缺了 onChange。
textarea 的写法和 input 完全一样，也是 value 加 onChange。在 HTML 里 textarea 的内容写在标签中间，在 React 里统一改成 value 属性。
提交事件要写在 form 上，而不是写在按钮上。这样用户点“发送”按钮，或者在输入框里按回车，都会触发提交。
dongge-react/src/components/MessageForm.tsx（片段）
import type { SubmitEvent } from 'react'
function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
event.preventDefault()
const text = content.trim()
if (text === '') {
setError('留言不能为空')
return
}
if (text.length > MAX_LENGTH) {
setError(`留言最多 ${MAX_LENGTH} 个字`)
return
}
// 校验通过：保存，清空，显示感谢
setContent('')
setError('')
setSent(true)
}
<form onSubmit={handleSubmit}>...</form>逐行解释：
SubmitEvent<HTMLFormElement>：参数的类型，意思是“一个发生在表单元素上的提交事件”。它从 react 导入，所以用 import type。旧教程里你常会看到 FormEvent，新版的 React 类型已经把它标记为过时，用 SubmitEvent 更准确。event.preventDefault()：和 DAY 21 一样，阻止浏览器“提交表单并刷新页面”的默认行为。不写这一行，页面一刷新，所有 state 都没了。content.trim()：去掉首尾的空格和换行。只输入几个空格也算空。return，后面的代码不再执行。错误信息和感谢提示都是昨天、前天学过的东西在组合：错误用 {error && <p className="error">{error}</p>}，error 是空字符串时什么都不显示；感谢用 if 提前 return，sent 为 true 时整个组件换成感谢卡片。这就是 React 表单的基本套路：每一种界面状态（正在填写、出错、已发送）都用 state 表示，界面根据 state 条件渲染。
npm install -D @types/react@latest @types/react-dom@latest 更新类型包；实在不行，先把两处 SubmitEvent 换成 FormEvent，代码一样能运行。回想一下：组件的本职工作是“根据 props 和 state 算出界面”。像一个计算器，给同样的输入，就得到同样的输出，这样的函数叫纯函数。
但有些事不属于“算出界面”：修改浏览器标签页上的标题、把数据写进 localStorage、开一个定时器、向服务器请求数据。这些事会影响组件之外的世界，叫副作用。如果直接写在组件函数里，每次渲染都会执行，而且在 React 还没把界面更新到页面上时就执行了，时机不对。
举个具体的例子。假设你直接在 App 函数体里写 localStorage.setItem('dongge-theme', theme)：访客在留言框里每打一个字、每点一次筛选，只要 App 重新渲染，这一行就会执行一次，哪怕 theme 根本没变。组件函数会被调用很多次，调用的时机也由 React 决定，你不应该在里面“顺手做点别的事”。
useEffect 就是为副作用准备的：“等这次渲染完成、页面更新之后，再执行这段代码。”而且你可以告诉它“只有某些值变了才需要再执行”，这样就不会做无用功。可以把它理解成一个“同步器”：它负责让组件之外的某样东西（标签页标题、localStorage）和组件里的某个值保持一致。
dongge-react/src/App.tsx（片段）
import { useEffect, useState } from 'react'
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])逐行解释：
useEffect(函数, 依赖数组)：第一个参数是你要做的事，第二个参数告诉 React“什么时候需要重新做”。document.title = ...：修改浏览器标签页上显示的标题。页面本身不管这个，它属于“组件之外的世界”。[theme]：依赖数组。意思是“第一次渲染后执行一次，以后只有 theme 变了才再执行”。你切换风格，标签页标题会变成“三岁的东哥 · 街头”；你点筛选按钮，theme 没变，这段代码就不执行。和 useState 一样，useEffect 也是 Hook，只能写在组件的最顶层，不能放进 if 里，也不能写在“提前 return”的后面。
依赖数组是今天最重要、也最容易混的地方。用一张表记住：
| 写法 | 什么时候执行 | 常见用途 |
|---|---|---|
useEffect(fn) 不写 | 每一次渲染之后都执行 | 很少用，容易执行太多次 |
useEffect(fn, []) 空数组 | 只在组件第一次出现在页面上之后执行一次 | 只需要做一次的准备工作，比如页面打开时读取一次数据 |
useEffect(fn, [theme]) 写变量 | 第一次渲染后执行，之后只要数组里的任何一个值变了，就再执行 | 让外部世界和某个 state 保持同步，比如把 theme 存进 localStorage |
React 怎么知道“变了没有”？每次渲染后，它把依赖数组里的每一项和上一次的比较，有一项不同就执行。空数组没有任何东西可比，所以只在第一次执行；不写数组等于“不用比，每次都执行”。
一条规则：effect 里用到了哪些 props 和 state，就要把它们都写进依赖数组。如果你在 effect 里用了 theme，却写了空数组，effect 只会用到第一次渲染时的 theme，之后怎么切换都不会同步，这是新手最常见的 bug。
还有一个开发时会吓到你的现象：在 npm run dev 下，空数组的 effect 可能会打印两次。这是因为 main.tsx 里包着 <StrictMode>（严格模式），它在开发环境下会故意把组件“装上、拆下、再装上”，帮你检查 effect 写得是否经得起重复执行。上线后的正式版本只执行一次。不要为了这个去删掉 StrictMode。
effect 还可以返回一个清理函数，React 会在下次执行 effect 之前、或者组件从页面上消失时调用它。比如感谢提示 5 秒后自动消失：
useEffect(() => {
if (!sent) {
return
}
const timer = setTimeout(() => setSent(false), 5000)
return () => clearTimeout(timer)
}, [sent])sent 变成 true 时开一个 5 秒的定时器；返回的 () => clearTimeout(timer) 负责善后：如果 5 秒内用户已经点了“再写一条”，或者离开了这个组件，定时器会被取消，不会在奇怪的时候把状态改掉。这就像出门前约好“5 秒后关灯”，如果你提前自己关了灯，就要把这个约定撤销。
学会 useEffect 以后，很多人会什么都往里塞。React 官方专门写了一篇文章叫“你可能不需要 Effect”。判断方法很简单，问自己：这件事是因为“用户做了某个操作”才发生的，还是因为“组件显示出来了、某个值变了”就要发生？
还有一个细节：页面打开时，要从 localStorage 读出上次的风格。你可能想写一个空数组的 effect，在里面读出来再 setTheme。这样也能工作，但页面会先用默认的绅士风格渲染一次，再变成保存的风格，访客会看到颜色闪一下。更好的写法是把“读取”交给 useState 的初始值：
dongge-react/src/App.tsx（片段）
const THEME_KEY = 'dongge-theme'
function getSavedTheme(): World {
const saved = localStorage.getItem(THEME_KEY)
if (saved === 'gentleman' || saved === 'street' || saved === 'thai') {
return saved
}
return 'gentleman'
}
// 组件里：
const [theme, setTheme] = useState<World>(getSavedTheme)
useEffect(() => {
localStorage.setItem(THEME_KEY, theme)
}, [theme])逐行解释：
getSavedTheme：一个写在组件外面的普通函数。localStorage.getItem 返回字符串，或者没有存过时返回 null。=== 比较：确认读出来的确实是三个世界之一。localStorage 里的东西谁都能改（访客可以在开发者工具里手动改），不能直接相信。比较通过后，TypeScript 也就知道 saved 一定是 World 类型了，可以直接 return。useState<World>(getSavedTheme)：注意这里传的是函数本身，没有加括号。传函数时，React 只在第一次渲染时调用它，拿返回值当初始值；如果写成 getSavedTheme()，每次渲染都会读一次 localStorage，虽然结果被忽略，但白白浪费。这样一读一写，风格就能跨刷新保存了。
新建留言表单组件：两个受控输入框
在 src/components/ 下新建 MessageForm.tsx。先只写两个受控输入框和字数统计，不写提交：
import { useState } from 'react'
const MAX_LENGTH = 200
export default function MessageForm() {
const [nickname, setNickname] = useState('')
const [content, setContent] = useState('')
return (
<form className="message-form">
<label htmlFor="nickname">你的昵称（可以不填）</label>
<input
id="nickname"
value={nickname}
onChange={(event) => setNickname(event.target.value)}
maxLength={20}
/>
<label htmlFor="content">想对东哥说的话</label>
<textarea
id="content"
rows={4}
value={content}
onChange={(event) => setContent(event.target.value)}
/>
<p className="counter">
{content.length} / {MAX_LENGTH}
</p>
</form>
)
}放进页面，加样式
在 App.tsx 顶部加 import MessageForm from './components/MessageForm'，在“最近的穿搭”那个 Section 后面加：
<Section title="给东哥留言">
<MessageForm />
</Section>在 App.css 末尾追加：
dongge-react/src/App.css
.message-form {
display: flex;
flex-direction: column;
gap: 8px;
}
.message-form input,
.message-form textarea {
padding: 10px 12px;
border: 1px solid #cccccc;
border-radius: 12px;
font: inherit;
}
.message-form button,
.thanks button {
padding: 12px 24px;
border: none;
border-radius: 999px;
background: var(--accent);
color: #ffffff;
font: inherit;
cursor: pointer;
}
.counter {
font-size: 0.875rem;
text-align: right;
opacity: 0.7;
}
.error {
color: #c62828;
}
.thanks {
padding: 24px;
border-radius: 16px;
background: var(--card);
text-align: center;
}onChange 那一行临时删掉，确认输入框打不进字，控制台有警告，然后加回去。完成提交、校验和感谢
把 MessageForm.tsx 补全成下面的样子。先自己按上午第 3 节写，再对照：
dongge-react/src/components/MessageForm.tsx
import { useState } from 'react'
import type { SubmitEvent } from 'react'
type Message = {
nickname: string
content: string
createdAt: string
}
const MAX_LENGTH = 200
const STORAGE_KEY = 'dongge-messages'
export default function MessageForm() {
const [nickname, setNickname] = useState('')
const [content, setContent] = useState('')
const [error, setError] = useState('')
const [sent, setSent] = useState(false)
function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
event.preventDefault()
const text = content.trim()
if (text === '') {
setError('留言不能为空')
return
}
if (text.length > MAX_LENGTH) {
setError(`留言最多 ${MAX_LENGTH} 个字`)
return
}
const message: Message = {
nickname: nickname.trim(),
content: text,
createdAt: new Date().toISOString(),
}
const saved = localStorage.getItem(STORAGE_KEY)
const messages: Message[] = saved ? JSON.parse(saved) : []
localStorage.setItem(STORAGE_KEY, JSON.stringify([...messages, message]))
setNickname('')
setContent('')
setError('')
setSent(true)
}
if (sent) {
return (
<div className="thanks">
<p>收到了，谢谢你的留言。</p>
<button type="button" onClick={() => setSent(false)}>
再写一条
</button>
</div>
)
}
return (
<form className="message-form" onSubmit={handleSubmit}>
<label htmlFor="nickname">你的昵称（可以不填）</label>
<input
id="nickname"
value={nickname}
onChange={(event) => setNickname(event.target.value)}
maxLength={20}
/>
<label htmlFor="content">想对东哥说的话</label>
<textarea
id="content"
rows={4}
value={content}
onChange={(event) => setContent(event.target.value)}
/>
<p className="counter">
{content.length} / {MAX_LENGTH}
</p>
{error && <p className="error">{error}</p>}
<button type="submit">发送</button>
</form>
)
}保存留言的这几行和 DAY 21 的思路一样：先读出已有的留言数组（没有就用空数组），用展开运算符加上新的一条，再整个写回去。JSON.stringify 和 JSON.parse 负责在“数组”和“字符串”之间转换，因为 localStorage 只能存字符串。
把三种情况都测一遍
第一，什么都不写直接点发送，应该看到“留言不能为空”，页面没有刷新。第二，只输入几个空格再发送，也应该提示为空。第三，粘贴一段超过 200 字的文字，应该提示“留言最多 200 个字”。第四，写一句正常的话发送，应该看到感谢卡片，点“再写一条”回到空表单。
然后打开开发者工具，切到 Application（应用）面板，左侧找到 Local Storage 下的 http://localhost:5173，能看到 dongge-messages 里存着你刚发的留言。
用 useEffect 同步标签页标题
在 App.tsx 顶部把导入改成 import { useEffect, useState } from 'react'，并把 getWorldName 一起导入：import { worlds, getWorldName } from './data/worlds'。在两个 useState 下面加：
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])实验：三种依赖数组
在 App 里临时加三个 effect：
useEffect(() => {
console.log('A 不写依赖：每次渲染后都执行')
})
useEffect(() => {
console.log('B 空数组：只在第一次渲染后执行')
}, [])
useEffect(() => {
console.log('C 依赖 theme：theme 变了才执行', theme)
}, [theme])刷新页面，看控制台（开发环境下可能每条出现两次，原因见上午第 5 节）。然后点筛选按钮：只有 A 打印，因为 filter 变了导致重新渲染，但 theme 没变。再点风格按钮：A 和 C 都打印。最后在留言框里打几个字：三条都不打印，因为变的是 MessageForm 自己的 state，App 没有重新渲染。
记录下你看到的现象，这就是今晚验收第 1 题的答案。实验结束后删掉这三个 effect。
让风格在刷新后保留
把 App.tsx 改成下面的完整版本：
dongge-react/src/App.tsx
import { useEffect, useState } from 'react'
import type { World } from './types'
import Avatar from './components/Avatar'
import Intro from './components/Intro'
import PlatformButton from './components/PlatformButton'
import Section from './components/Section'
import LookList from './components/LookList'
import MessageForm from './components/MessageForm'
import { platforms } from './data/platforms'
import { worlds, getWorldName } from './data/worlds'
import { looks } from './data/looks'
import './App.css'
type Filter = World | 'all'
const THEME_KEY = 'dongge-theme'
function getSavedTheme(): World {
const saved = localStorage.getItem(THEME_KEY)
if (saved === 'gentleman' || saved === 'street' || saved === 'thai') {
return saved
}
return 'gentleman'
}
export default function App() {
const [theme, setTheme] = useState<World>(getSavedTheme)
const [filter, setFilter] = useState<Filter>('all')
useEffect(() => {
localStorage.setItem(THEME_KEY, theme)
}, [theme])
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])
const visibleLooks = filter === 'all' ? looks : looks.filter((look) => look.world === filter)
return (
<div className={`app theme-${theme}`}>
<main className="links-page">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<div className="switcher">
{worlds.map((world) => (
<button
key={world.slug}
type="button"
className={theme === world.slug ? 'active' : ''}
onClick={() => setTheme(world.slug)}
>
{world.name}
</button>
))}
</div>
<nav className="platforms" aria-label="东哥的平台">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} color={platform.color} />
))}
</nav>
<Section title="三个世界">
<ul className="world-list">
{worlds.map((world) => (
<li key={world.slug}>
<strong>{world.name}</strong> · {world.feeling}
<p>{world.tagline}</p>
</li>
))}
</ul>
</Section>
<Section title="最近的穿搭">
<div className="filters">
<button
type="button"
className={filter === 'all' ? 'active' : ''}
onClick={() => setFilter('all')}
>
全部
</button>
{worlds.map((world) => (
<button
key={world.slug}
type="button"
className={filter === world.slug ? 'active' : ''}
onClick={() => setFilter(world.slug)}
>
只看{world.name}
</button>
))}
</div>
<LookList looks={visibleLooks} />
</Section>
<Section title="给东哥留言">
<MessageForm />
</Section>
</main>
</div>
)
}dongge-theme 的值是 street。动手验证“不能相信 localStorage”
在 Application 面板里双击 dongge-theme 的值，手动改成 abc，刷新页面。页面应该回到绅士风格，而不是出现一个没有颜色的页面。这就是 getSavedTheme 里三个比较的作用。
（加分）感谢提示 5 秒后自动回到表单
在 MessageForm.tsx 顶部把导入改成 import { useEffect, useState } from 'react'，然后把上午第 5 节那段带清理函数的 useEffect 加到四个 useState 的下面。一定要放在 if (sent) 那段提前 return 的上面，否则 sent 为 true 时这个 Hook 会被跳过，React 会报错。
请 Claude 审查，然后提交
把 MessageForm.tsx 和 App.tsx 发给 Claude，用“问 Claude”的第一条提示词。重点看它对 effect 依赖数组、校验逻辑的意见。改完后提交：
git add .
git commit -m "DAY 30 受控表单和用 useEffect 保存风格"明天你会把 DAY 23 到 25 做的测试小游戏搬进 React，用到今天和前两天学的所有东西。
value 却没写 onChange，或者 onChange 里没有把 event.target.value 存进 state。两者必须成对出现。event.preventDefault()，或者把 onSubmit 写到了按钮上而不是 form 上。useState()（undefined）。输入框的 state 初始值要写空字符串 useState('')。useEffect 的依赖数组写空数组、不写、写变量，分别会怎样？
不写依赖数组：每一次渲染之后都会执行，state 或 props 一变就执行一次。写空数组：只在组件第一次出现在页面上之后执行一次，之后不管怎么重新渲染都不再执行（开发环境的 StrictMode 下会故意多执行一次来做检查）。写变量，比如 [theme]：第一次渲染后执行一次，之后每次渲染时 React 会比较数组里的值和上一次是否相同，只要有一个变了就再执行。effect 里用到的 props 和 state 都应该写进依赖数组，否则 effect 会一直用旧值。
今天保存留言写在了 handleSubmit 里，保存风格却用了 useEffect。为什么不统一都用 useEffect？
保存留言是“用户点了发送”这个具体操作引起的，放在事件处理函数里最直接，逻辑也清楚：校验通过就保存。保存风格是“只要 theme 变了，就要和 localStorage 保持同步”，不管 theme 是被哪个按钮改的，用 effect 统一处理，不用在每个修改 theme 的地方都写一遍保存。判断标准：由某个操作引起的放事件处理函数，由某个值变化引起、需要和外部同步的放 useEffect。
什么是受控组件？下面这个输入框会有什么问题？
const [content, setContent] = useState('')
<textarea value={content} />受控组件是指输入框显示的值完全由 React 的 state 决定，用户输入时通过 onChange 更新 state，state 再决定显示什么。这个 textarea 只有 value 没有 onChange：用户输入时 state 不会变，React 又会把显示内容改回 state 里的空字符串，所以根本打不进字，控制台还会警告。要加上 onChange={(event) => setContent(event.target.value)}。
onAnswer、onRestart）让子组件通知父组件修改 state，并写出它们的 TypeScript 类型。DAY 23 到 25，你在 ~/code/quiz 里做过测试小游戏。回想一下那时的结构：一个脚本文件里有 currentIndex（当前第几题）和 answers（选过的答案）两个变量，还有一个 renderQuestion() 函数，每次答完一题，你手动更新变量，再调用函数去改页面上的题目文字、按钮和进度。所有东西挤在一起，数据和页面靠你自己记得同步。
那个版本能用，但你当时一定遇到过这样的麻烦：改了 answers，忘了同时更新进度文字；点“再测一次”，要记得把变量清零、把结果区域藏起来、把题目区域显示出来，漏一步页面就乱了。原因在于页面和数据是两套东西，全靠你手动对齐。这几天你已经体会到 React 的思路：只管数据，页面根据数据自动算出来。今天把这个思路用在一个有好几步流程的小应用上。
用 React 重写时，你自然会想把它拆成几个组件：开始页、题目卡片、进度条、结果页。拆开以后，一个新问题出现了：这些组件都需要知道“现在第几题、选了什么”，这份数据应该放在哪个组件里？这就是今天的核心：状态提升。
React 的页面是一棵组件树：App 在最上面，里面套着 Section，Section 里套着别的组件。数据在这棵树上只有一个流动方向：从上往下，通过 props 传递。父组件可以把数据传给子组件，子组件不能反过来直接改父组件的数据，兄弟组件之间也不能直接传数据。这叫单向数据流。
单向的好处是好查错：页面上某个东西显示错了，你只要顺着树往上找，看数据是从哪一层传下来的，一定能找到源头。
今天测试小游戏的组件树是这样的：
App
└── Section（测一测）
└── Quiz state：started、answers
├── QuizStart props：total、onStart
├── ProgressBar props：current、total
├── QuestionCard props：question、onAnswer
└── ResultCard props：outcome、onRestartQuiz 是这个小游戏的“总管”，它持有 state，决定此刻显示哪个子组件；四个子组件都只负责显示，它们需要的东西全部通过 props 拿到。这种“一个组件管数据，几个组件管显示”的分工，在 React 里非常常见。
假设你一开始把 answers 放在 QuestionCard 里：用户点一个选项，QuestionCard 自己记下答案。看起来很自然，但马上遇到问题：
解决办法是：把 state 从子组件“提升”到它们最近的共同父组件里，也就是 Quiz。Quiz 持有 answers，再通过 props 分别交给需要它的子组件。
打个比方：一家店有三个前台（三个子组件），库存表如果每个前台各记一份，很快就会对不上。正确做法是库存表只放在经理（父组件）手里，一份就够；经理把最新的库存情况抄给每个前台（props）。前台不能自己改库存，客人买了东西，前台打电话告诉经理（回调函数），经理改完库存表，再把新的发下去。
怎么找“最近的共同父组件”？在组件树上，把所有需要这份数据的组件圈出来，往上找，第一个把它们都包在里面的组件就是。ProgressBar、QuestionCard、ResultCard 往上找，第一个共同的祖先是 Quiz。为什么不放到更上面的 App？因为 App 用不到这些数据，放太高会让 App 变复杂，数据也要多传好几层。state 放在“刚好够用”的最低位置。
state 在 Quiz 里，可“用户点了哪个选项”这件事发生在 QuestionCard 里。子组件怎么把消息传上去？答案是：父组件把一个函数通过 props 传给子组件，子组件在合适的时候调用它。你在 DAY 29 已经见过这个思路的预告。
dongge-react/src/quiz/QuestionCard.tsx
import type { QuizQuestion, World } from '../types'
type QuestionCardProps = {
question: QuizQuestion
onAnswer: (world: World) => void
}
export default function QuestionCard({ question, onAnswer }: QuestionCardProps) {
return (
<div className="question-card">
<h3>{question.text}</h3>
<div className="options">
{question.options.map((option) => (
<button key={option.text} type="button" onClick={() => onAnswer(option.world)}>
{option.text}
</button>
))}
</div>
</div>
)
}逐行解释：
QuizQuestion：DAY 26 你给题目定义的类型，每道题有 id、text（题目文字）和 options（选项数组）。下午会把它搬进这个项目的 types.ts。onAnswer: (world: World) => void：这是一个“函数类型”。意思是：onAnswer 是一个函数，接收一个 World 类型的参数，不返回任何东西（void 表示“没有返回值”）。DAY 26 你学过给函数写类型，这里是把同样的写法用在 props 上。question.options.map(...)：昨天之前学的列表渲染，每个选项一个按钮。key={option.text}：同一道题里，选项的文字不会重复，可以当 key。onClick={() => onAnswer(option.world)}：点击时调用父组件给的函数，把这个选项对应的世界告诉父组件。QuestionCard 自己不记任何东西，也不关心父组件拿到之后做什么。在 Quiz 里这样使用它：
function handleAnswer(world: World) {
setAnswers([...answers, world])
}
<QuestionCard question={questions[currentIndex]} onAnswer={handleAnswer} />Quiz 把自己的 handleAnswer 交给子组件，名字叫 onAnswer。用户点选项，QuestionCard 调用 onAnswer，实际执行的是 Quiz 的 handleAnswer，它用 DAY 29 学的展开写法生成一个新数组。state 一变，Quiz 重新渲染，把下一道题和新的进度传下去。
记住这个口诀：数据往下传（props），事件往上报（回调）。习惯上，props 里的回调叫 onXxx，父组件里对应的处理函数叫 handleXxx。
一个测试小游戏，你可能会想到很多 state：是否开始、当前第几题、答案数组、是否结束、结果是哪个世界。先别急着全写上，挨个问一句：它能不能从别的 state 算出来？
currentIndex = answers.length，答了 0 题就是第 0 题（数组下标从 0 开始），答了 2 题就是第 2 题。可以算出来。pickWorld(answers) 算一下。可以算出来。所以只需要两个 state：started 和 answers。如果你把 currentIndex 也存成 state，每次答题就得同时改两个 state，哪天你加一个“上一题”按钮，只减了 currentIndex 忘了删答案，两个数字就对不上了。state 越少，出错的地方越少。这和 DAY 29 的 visibleLooks 是同一个道理。
有了这两个 state，Quiz 该显示什么就很清楚了：没开始，显示开始页；答完了，显示结果；否则显示进度条和当前题目。三种情况，用 if 提前 return 依次判断。
你可以把这个过程想成一张流程图：开始页 → 第 1 题 → …… → 第 6 题 → 结果页 → （再测一次）→ 开始页。流程图上的每一个“格子”，都应该能由 state 唯一地确定下来。started 为 false 就是开始页；started 为 true 时，answers 有几项就是第几个格子；answers 满了就是结果页。设计 state 时，先画出这样一张流程图，再问“最少需要记住哪些东西才能知道现在在哪一格”，这是一个非常好用的方法，以后做后台的“草稿、已发布”状态时也用得上。
DAY 23 你写了 6 道题（questions），DAY 24 写了计分函数和三段结果文案（score、results），DAY 25、26 把它们改成了 TypeScript 并定义好了类型。这些文件有一个共同点：它们和界面无关。题目和文案是纯数据；计分函数给它一组答案，它还你一个结果，不读页面、不改页面，同样的输入永远得到同样的输出，这样的函数叫纯函数。
和界面无关的代码，最大的好处是能原样搬家：从原生 TypeScript 项目搬到 React 项目，只需要改一下 import 的路径。下午你会把 ~/code/quiz/src/ 里的 questions.ts、results.ts、score.ts 直接复制过来。回顾一下 DAY 26 版的 score.ts，搬过来后只有第一行变了：
dongge-react/src/quiz/score.ts（从 quiz 项目复制，只改了第一行）
import type { QuizOutcome, Scores, World } from "../types";
const WORLDS: World[] = ["gentleman", "street", "thai"];
export function countScores(answers: World[]): Scores {
const scores: Scores = { gentleman: 0, street: 0, thai: 0 };
answers.forEach((world) => {
scores[world] += 1;
});
return scores;
}
export function pickWorld(answers: World[]): QuizOutcome {
const scores = countScores(answers);
const maxScore = Math.max(...Object.values(scores));
const topWorlds = WORLDS.filter((world) => scores[world] === maxScore);
if (topWorlds.length === 1) {
return { world: topWorlds[0], topWorlds, scores };
}
// 同分：从最后一题往前找，第一个属于同分世界的选择就是结果
for (let i = answers.length - 1; i >= 0; i -= 1) {
const answer = answers[i];
if (topWorlds.includes(answer)) {
return { world: answer, topWorlds, scores };
}
}
return { world: topWorlds[0], topWorlds, scores };
}快速回顾它做了什么：
from "./types.ts"，因为 quiz 项目的类型文件和它在同一个文件夹。现在类型统一放在 src/types.ts，score.ts 在 src/quiz/ 里，所以要写 "../types"，往上退一级。countScores：每个答案给对应的世界加 1 分，返回三个世界的得分。Scores 就是 Record<World, number>，三个世界一个都不能少。pickWorld：找出最高分，列出所有达到最高分的世界（topWorlds）。只有一个就是结果；有并列时，从最后一题往前找，第一个属于并列世界的选择胜出。这是你 DAY 18 验收题“同分时怎么办”的答案：越靠后的选择，越能代表此刻的心情。QuizOutcome 不只有结果世界，还带着 topWorlds 和 scores。结果页可以用 topWorlds 判断“是不是平局”，给出一句说明，就像 DAY 24 做的那样。score.ts 里是双引号加分号，而你今天新写的组件是单引号不加分号。两种写法完全等价，不影响运行。复制过来的文件不必为了风格统一去改，能用的代码不要为了好看而冒险去动，这也是一种工程习惯。DAY 51 你还会给 pickWorld 写自动化测试，那时就能更放心地改它。
从 DAY 25 起，Claude 是你的审稿人。今天多一个用法：Plan 模式（计划模式）。在这个模式下，Claude 只读文件、出方案，不会修改任何文件。你用它来讨论“组件怎么拆、state 放哪”，就像开工前和一位有经验的同事在白板上画一画。
怎么用：在 Claude Code 里切换到 Plan 模式。终端版按 Shift + Tab，直到状态栏显示 plan mode on；桌面 App 在输入框附近的模式选项里选择 Plan。然后把需求讲清楚，并明确要求“只要方案，不要代码”。
拿到方案后，不要照单全收，用今天学的三个问题去检查它：
如果 Claude 的方案和本课件的组件树不一样，不一定谁错。比如它可能建议把开始页和结果页合并，或者多一个 OptionButton 组件。想清楚理由再决定用哪个。决定之后，退出 Plan 模式，代码由你自己一个文件一个文件地写，写完再请 Claude 审查。这样你既学到了“怎么设计”，又练到了“怎么实现”。
用 Plan 模式讨论组件树
在 ~/code/dongge-react 打开 Claude Code，切到 Plan 模式，发送“问 Claude”里的第一条提示词。读它给出的方案，用上午第 7 节的三个问题检查，在笔记里写下：你采用了哪些建议、没采用哪些、为什么。然后退出 Plan 模式。
把测试的类型搬进 types.ts
打开 ~/code/quiz/src/types.ts（DAY 26 写的），把下面这 5 个类型复制到 ~/code/dongge-react/src/types.ts 的末尾。World 已经有了，不要重复复制；Look 和 Platform 在官网项目里已经有自己的版本，也不要复制。
dongge-react/src/types.ts（末尾追加）
export interface QuizOption {
text: string;
world: World;
}
export interface QuizQuestion {
id: number;
text: string;
options: QuizOption[];
}
export interface WorldResult {
label: string;
name: string;
feeling: string;
summary: string;
detail: string;
recommend: string;
}
export type Scores = Record<World, number>;
export interface QuizOutcome {
world: World;
topWorlds: World[];
scores: Scores;
}这些是 DAY 26 原样的 interface 写法，和文件里其他用 type 写的类型放在一起没有问题。
复制题目、结果文案和计分函数
cd ~/code/dongge-react
mkdir -p src/quiz
cp ~/code/quiz/src/questions.ts ~/code/quiz/src/results.ts ~/code/quiz/src/score.ts src/quiz/
ls src/quiz测试小游戏的所有文件都放在 src/quiz/ 里。复制完，三个文件的第一行都会报红，因为它们还在找同一个文件夹里的 ./types.ts。逐个打开，把第一行改成：
// src/quiz/questions.ts 的第一行
import type { QuizQuestion } from "../types";
// src/quiz/results.ts 的第一行
import type { World, WorldResult } from "../types";
// src/quiz/score.ts 的第一行
import type { QuizOutcome, Scores, World } from "../types";文件里的其他内容一个字都不用动。如果你的 quiz 项目里缺了某个文件，或者和 DAY 26 的结构不一样，就回到 DAY 23（题目）、DAY 24（结果文案）、DAY 26（score.ts 和类型）的课件，把当时的代码补齐再复制。
pickWorld 上，能看到它的类型是 (answers: World[]) => QuizOutcome。先单独测一下计分函数
在 src/quiz/ 里还没有组件用到 pickWorld，先用 DAY 24 的老办法验证它搬家后还正常。临时在 src/main.tsx 的 import 下面加两行：
import { pickWorld } from './quiz/score'
console.log(pickWorld(['gentleman', 'street', 'thai', 'gentleman', 'street', 'thai']))打开浏览器控制台，应该看到 world 是 thai，topWorlds 里有三个世界（2:2:2 平局，最后一题选的是泰风）。确认之后把这两行删掉。
写开始页和进度条
dongge-react/src/quiz/QuizStart.tsx
type QuizStartProps = {
total: number
onStart: () => void
}
export default function QuizStart({ total, onStart }: QuizStartProps) {
return (
<div className="quiz-start">
<h3>你现在最需要哪个东哥？</h3>
<p>{total} 道题，一分钟做完。</p>
<button type="button" onClick={onStart}>
开始
</button>
</div>
)
}dongge-react/src/quiz/ProgressBar.tsx
type ProgressBarProps = {
current: number
total: number
}
export default function ProgressBar({ current, total }: ProgressBarProps) {
const percent = Math.round((current / total) * 100)
return (
<div className="progress">
<p>
第 {current} / {total} 题
</p>
<div className="progress-track">
<div className="progress-fill" style={{ width: `${percent}%` }} />
</div>
</div>
)
}onStart: () => void 表示“一个不需要参数、也不返回东西的函数”。style={{ width: ... }} 是 JSX 里写行内样式的方法：外层花括号表示“这里是 JS 表达式”，里层花括号是一个对象，CSS 属性名用驼峰写法。宽度随题号变化，没法提前写在 CSS 文件里，所以这里用行内样式。
写题目卡片
新建 src/quiz/QuestionCard.tsx，内容是上午第 4 节的完整代码。
写结果页
dongge-react/src/quiz/ResultCard.tsx
import type { QuizOutcome } from '../types'
import { results } from './results'
type ResultCardProps = {
outcome: QuizOutcome
onRestart: () => void
}
export default function ResultCard({ outcome, onRestart }: ResultCardProps) {
const result = results[outcome.world]
const tieNames = outcome.topWorlds.map((world) => results[world].label).join('、')
return (
<div className="result-card">
<p>你最需要的是</p>
<p className="result-world">{result.name}</p>
<p>他给你的是：{result.feeling}</p>
<p>{result.summary}</p>
<p>{result.detail}</p>
{outcome.topWorlds.length > 1 && (
<p className="tie-note">
你在{tieNames}之间打了个平手，按你最后的选择，结果算作{result.label}。
</p>
)}
<p>{result.recommend}</p>
<button type="button" onClick={onRestart}>
再测一次
</button>
</div>
)
}结果页显示的内容和 DAY 24 的结果卡片一样，文案全部来自复制过来的 results.ts。results[outcome.world] 能直接取到，因为 results 的类型是 Record<World, WorldResult>，三个世界一定都有，不会是 undefined。平局说明用了 && 条件渲染，只有 topWorlds 超过一个时才显示；tieNames 用 map 把并列的世界换成中文名，再用 join 连成“绅士、泰风”这样的一串。
写总管组件 Quiz
这是今天最重要的文件，先根据上午第 3 到 5 节自己写一遍，写不出来再对照：
dongge-react/src/quiz/Quiz.tsx
import { useState } from 'react'
import type { World } from '../types'
import { questions } from './questions'
import { pickWorld } from './score'
import QuizStart from './QuizStart'
import ProgressBar from './ProgressBar'
import QuestionCard from './QuestionCard'
import ResultCard from './ResultCard'
export default function Quiz() {
const [started, setStarted] = useState(false)
const [answers, setAnswers] = useState<World[]>([])
const currentIndex = answers.length
const isFinished = currentIndex === questions.length
function handleAnswer(world: World) {
setAnswers([...answers, world])
}
function handleRestart() {
setAnswers([])
setStarted(false)
}
if (!started) {
return <QuizStart total={questions.length} onStart={() => setStarted(true)} />
}
if (isFinished) {
return <ResultCard outcome={pickWorld(answers)} onRestart={handleRestart} />
}
return (
<div className="quiz">
<ProgressBar current={currentIndex + 1} total={questions.length} />
<QuestionCard question={questions[currentIndex]} onAnswer={handleAnswer} />
</div>
)
}注意三点：useState<World[]>([]) 必须写类型，因为空数组看不出里面会放什么；进度条显示 currentIndex + 1，因为给人看的题号从 1 开始；判断顺序是“没开始、已结束、进行中”，如果把 isFinished 的判断放到最后，答完第 6 题时 questions[6] 是 undefined，页面会报错。
放进页面，加样式
在 App.tsx 顶部加 import Quiz from './quiz/Quiz'，在“给东哥留言”后面加：
<Section title="测一测">
<Quiz />
</Section>在 App.css 末尾追加：
dongge-react/src/App.css
.quiz-start,
.question-card,
.result-card {
padding: 24px;
border-radius: 16px;
background: var(--card);
text-align: center;
}
.options {
display: flex;
flex-direction: column;
gap: 12px;
margin-top: 16px;
}
.options button,
.quiz-start button,
.result-card button {
padding: 12px 20px;
border: 1px solid var(--accent);
border-radius: 999px;
background: transparent;
color: var(--accent);
font: inherit;
cursor: pointer;
}
.quiz-start button,
.result-card button {
background: var(--accent);
color: #ffffff;
}
.progress {
margin-bottom: 16px;
}
.progress-track {
height: 8px;
overflow: hidden;
border-radius: 999px;
background: rgba(128, 128, 128, 0.25);
}
.progress-fill {
height: 100%;
background: var(--accent);
transition: width 0.3s;
}
.result-world {
margin: 8px 0;
font-size: 2rem;
font-weight: bold;
}
.tie-note {
font-size: 0.875rem;
opacity: 0.8;
}专门测一测同分的情况
打开 src/quiz/questions.ts，看清每道题里哪个选项对应哪个世界（选项的顺序每题不一样）。然后在页面上按“绅士、街头、泰风、绅士、街头、泰风”的世界顺序作答，三个世界都是 2 分，结果应该是最后一题选的泰风，并且显示平局说明。再按“绅士、绅士、绅士、街头、街头、街头”答一次，3:3 平局，结果应该是街头。
console.log(answers)，看记录下来的答案是不是你以为的那样。（加分）加一个“上一题”按钮
在 Quiz 里加一个处理函数，删掉最后一个答案，就回到了上一题：
function handleBack() {
setAnswers(answers.slice(0, -1))
}slice(0, -1) 返回一个去掉最后一项的新数组，不会改动原数组。自己想一想这个按钮应该放在哪个组件里、第 1 题时要不要显示，然后实现它。因为 currentIndex 是从 answers 算出来的，你只改了一个 state，题号和进度条就自动都对了。这就是上午第 5 节说的“state 越少越好”的回报。
请 Claude 审查，然后提交
把 src/quiz/ 下的文件发给 Claude，用“问 Claude”的第二条提示词请它审查。自己改完后提交：
git add .
git commit -m "DAY 31 React 版测试小游戏"明天你会学 Tailwind CSS，把 App.css 里越积越多的样式换成一种新写法。
onClick={onAnswer(option.world)}，渲染时就调用了。要包一层箭头函数：onClick={() => onAnswer(option.world)}。questions[6] 不存在。先判断没开始、再判断已结束，最后才渲染题目。src/types.ts。把第一行的 "./types.ts" 改成 "../types"，并确认那 5 个类型已经追加进 src/types.ts。setStarted(false)，忘了 setAnswers([])。答案没清空，一开始就是“已结束”。style={{ width: `${percent}%` }}，不能写成 HTML 那样的 style="width: 50%"。“当前第几题、选了什么”这些 state 放在哪个组件里？为什么？
放在 Quiz 组件里，而且只存了 answers（选了什么）和 started 两个 state，当前第几题直接用 answers.length 算出来。原因是：ProgressBar 要显示题号，QuestionCard 要知道显示哪道题并报告选择，ResultCard 要根据全部答案算结果、还要能清空重来，这几个组件都需要同一份数据。React 的数据只能从上往下传，兄弟组件之间不能直接共享，所以要把 state 提升到它们最近的共同父组件 Quiz 里，再通过 props 分给它们。放到更高的 App 里没有必要，App 用不到这些数据。
QuestionCard 不能修改 Quiz 的 state，那用户点了选项之后，答案是怎么被记下来的？
Quiz 把自己的 handleAnswer 函数通过名为 onAnswer 的 prop 传给 QuestionCard。用户点选项时，QuestionCard 调用 onAnswer(option.world)，实际执行的是 Quiz 的 handleAnswer，它调用 setAnswers 生成新数组。Quiz 重新渲染，把下一道题和新进度通过 props 传下去。也就是“数据往下传，事件往上报”。
有人建议在 Quiz 里再加一个 const [outcome, setOutcome] = useState<QuizOutcome | null>(null)，答完最后一题时把结果存进去。你同意吗？
不同意。结果完全可以在渲染时用 pickWorld(answers) 算出来，存成 state 就多了一份需要手动同步的数据：答完最后一题要记得 setOutcome，点“再测一次”要记得清空，加“上一题”功能时还要记得清空结果，漏一处就会出现结果和答案对不上的 bug。能从已有 state 算出来的值，就在渲染时计算。
@tailwindcss/vite 插件加上 CSS 里的 @import "tailwindcss";。sm:、md:、lg: 做手机优先的响应式。@theme 定义自己的颜色，让三个世界的风格切换在 Tailwind 下继续工作。打开你的 src/App.css，从 DAY 28 到 DAY 31，它已经涨到了一两百行：.look-card、.switcher button.active、.progress-fill……写着写着，你大概遇到过这几种烦恼：
.platform-btn 还是 .link-button？Tailwind CSS 换了一个思路：它提前准备好成百上千个“只做一件事”的小 class，比如 p-4 表示内边距 1rem，rounded-full 表示圆角拉满，bg-white 表示白色背景。你不再写 CSS 文件，而是把这些小 class 直接组合在元素上。这种做法叫 utility-first（工具类优先）。
打个比方：传统 CSS 像是每道菜都单独调一瓶专用酱汁，还要贴标签起名字；Tailwind 像是一排调料架，盐、糖、醋、酱油各一瓶，做什么菜就当场往里加。看一个对比：
/* 以前：DAY 27 写在 App.css 里 */
.platform-btn {
display: block;
padding: 14px;
border: 2px solid #1f2a2e;
border-radius: 12px;
background: #fff;
color: inherit;
font-weight: 600;
text-decoration: none;
}// 现在：直接写在组件上
<a className="block rounded-xl border-2 bg-white p-3.5 font-semibold">小红书</a>第一次看会觉得 class 好长好乱。但想一想：你的项目是用组件搭的，PlatformButton 只写一次，四个按钮都复用它。样式跟着组件走，打开一个文件就能看到它长什么样，删掉组件样式也跟着没了，不会留下没人敢删的 CSS。这正好解决了上面三个烦恼。
你可能会问：DAY 06 不是说过尽量别用 style="..." 行内样式吗？Tailwind 看起来也是把样式写在元素上，有什么区别？区别有两个。第一，行内样式可以写任意值，今天 13px、明天 15px，全站间距越来越乱；Tailwind 的数值是一套固定的刻度（4px、8px、12px、16px……），你只能在刻度里挑，页面自然整齐。第二，行内样式写不了悬停效果和媒体查询，而 Tailwind 可以用 hover:、md: 这样的前缀写，后面会讲。
需要说明的是，Tailwind 不是替代 CSS，而是用另一种方式写 CSS。p-4 背后就是 padding: 1rem，DAY 06 到 DAY 09 学的盒模型、Flexbox、Grid、媒体查询，今天一样都不会浪费，只是换了一种更短的写法。
Tailwind 现在的大版本是 v4，和网上很多旧教程（v3）的装法不一样：不再需要 tailwind.config.js 配置文件，也不需要 PostCSS 配置。对 Vite 项目，官方的步骤只有三步：
第一步，安装两个包：
npm install tailwindcss @tailwindcss/vitetailwindcss 是 Tailwind 本身，@tailwindcss/vite 是让 Vite 认识它的插件。
第二步，在 vite.config.ts 里加上插件：
dongge-react/vite.config.ts
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'
// https://vite.dev/config/
export default defineConfig({
plugins: [react(), tailwindcss()],
})Vite 在处理你的代码时，会按顺序经过 plugins 数组里的每个插件。原来只有 react()，现在多了 tailwindcss()。
第三步，在 CSS 文件里导入 Tailwind：
@import "tailwindcss";这一行放在 src/index.css 的最上面（main.tsx 已经导入了 index.css）。
装好之后，Tailwind 会自动扫描你项目里的文件，找出你用到了哪些 class，只为这些 class 生成 CSS。你写了 p-4，最终的 CSS 里才有 padding: 1rem；没用到的一个字节都不会打包进去。
Tailwind 的类名有规律，记住规律比背类名有用。大部分类都是“属性缩写 + 值”。
间距：p 是 padding，m 是 margin。后面加方向：x 左右、y 上下、t 上、b 下、l 左、r 右。数字 1 代表 0.25rem，也就是 4 像素。
| 类名 | 对应的 CSS |
|---|---|
p-4 | padding: 1rem（16px） |
px-6 py-3 | 左右 1.5rem，上下 0.75rem |
mt-8 | margin-top: 2rem |
mx-auto | 左右 margin 自动，常用于水平居中 |
gap-3 | flex 或 grid 子元素之间的间距 0.75rem |
颜色：bg- 背景色，text- 文字色，border- 边框色。后面跟颜色名和深浅，深浅从 50 到 950，数字越大越深，比如 bg-stone-100、text-red-600。还可以加斜杠表示透明度：bg-black/10 是 10% 不透明的黑色。
文字：text-sm、text-base、text-lg、text-xl、text-2xl 到 text-4xl 控制字号；font-medium、font-bold 控制粗细；text-center 居中；leading-relaxed 行高宽松一些。注意 text- 既能表示字号也能表示颜色，Tailwind 会根据后面的值自动判断。
尺寸和外观：w-full 宽度 100%；size-28 宽高都是 7rem；max-w-3xl 最大宽度限制；rounded-2xl、rounded-full 圆角；shadow-sm 轻微阴影；opacity-80 80% 不透明。
这么多类名不需要背。开始阶段，遇到想写的样式，先想“用普通 CSS 怎么写”，再去 Tailwind 官网左上角的搜索框搜这个 CSS 属性名，比如搜 padding、border-radius，文档里有完整的对照表。装了 IntelliSense 扩展后，鼠标停在类名上也能看到它生成的 CSS。用上一两周，常用的几十个类自然就记住了。
如果刻度里实在没有你要的值，可以用方括号写任意值，比如 w-[300px]、bg-[#1da1f2]。但这是“逃生出口”，用多了就又回到数值混乱的老路上，能用刻度里的值就用刻度。
DAY 07 和 DAY 08 学的 Flexbox、Grid，在 Tailwind 里都有一一对应的类：
// 一排按钮：横向排列、居中、间距 0.5rem
<div className="flex justify-center gap-2">...</div>
// 竖着排的按钮：主轴改成纵向
<div className="flex flex-col gap-3">...</div>
// 三列网格
<div className="grid grid-cols-3 gap-4">...</div>对照一下：flex 就是 display: flex；flex-col 是 flex-direction: column；justify-center 是 justify-content: center；items-center 是 align-items: center；grid-cols-3 是 grid-template-columns: repeat(3, minmax(0, 1fr))。你学过的概念一个都没变，只是写法变短了。DAY 07 的验收题“把一个方块放到页面正中间”，在 Tailwind 里就是 flex min-h-screen items-center justify-center。
还有一个几乎每个页面都会用到的组合：mx-auto max-w-3xl px-4。它的意思是“内容最宽 48rem，超出时左右自动留白居中，并且无论屏幕多窄，两边至少留 1rem 的空隙”。DAY 11 你为了手机适配专门处理过“内容贴边”的问题，这三个类一起就解决了。今天 App 的 main 就用这个组合当页面容器。
DAY 08 你学过“手机优先”：先写手机上的样式，再用媒体查询给大屏幕加规则。Tailwind 把媒体查询变成了前缀：
| 前缀 | 生效条件 | 对应 CSS |
|---|---|---|
| （不加） | 所有屏幕 | 无媒体查询 |
sm: | 屏幕宽度大于等于 40rem（640px） | @media (width >= 40rem) |
md: | 屏幕宽度大于等于 48rem（768px） | @media (width >= 48rem) |
lg: | 屏幕宽度大于等于 64rem（1024px） | @media (width >= 64rem) |
看一个你今天要用的例子：
<div className="flex flex-col gap-3 md:flex-row md:justify-center">
{/* 四个平台按钮 */}
</div>读法是：默认（手机上）竖着排；屏幕宽度达到 768px 及以上时，改成横着排并居中。这正是 DAY 07 的需求“平台按钮在手机上竖排、在电脑上横排”，以前要写一段媒体查询，现在只要加两个带 md: 的类。
新手最容易犯的错，是把 sm: 理解成“在小屏幕（手机）上”。其实正好相反：不带前缀的类才是给手机的，带前缀的是“从这个宽度开始往上”。所以写样式时先不加前缀把手机版写好，再想“到了平板、电脑要改什么”，给那几个类加上 md: 或 lg:。
再比如 DAY 08 的“三个世界：手机一列、平板两列、电脑三列”：grid gap-4 sm:grid-cols-2 lg:grid-cols-3，一行搞定。
除了屏幕宽度，前缀还可以表示“状态”：hover: 鼠标悬停时、focus: 获得焦点时、disabled: 被禁用时。比如 hover:opacity-90 就是“鼠标放上去时稍微变淡”，再加一个 transition，变化就是平滑的，这就是 DAY 09 学的过渡效果。
接下来是今天最关键的问题：三个世界的风格切换怎么办？Tailwind 自带的颜色是固定的，而你需要“同一个按钮，在绅士风格下是棕色，在街头风格下是橙色”。答案是用 @theme 定义你自己的颜色：
dongge-react/src/index.css（片段）
@import "tailwindcss";
@theme {
--color-page: #f4f1ea;
--color-ink: #1f1d1a;
--color-accent: #6b4f2a;
--color-card: #ffffff;
}
.theme-street {
--color-page: #141414;
--color-ink: #f5f5f5;
--color-accent: #ff5a1f;
--color-card: #242424;
}逐行解释：
@theme { ... }：Tailwind v4 的主题设置，写在 CSS 里，这就是它不再需要 tailwind.config.js 的原因。--color-accent: #6b4f2a;：以 --color- 开头的变量，Tailwind 会自动生成对应的类：bg-accent、text-accent、border-accent 都能用了。--color-page 生成 bg-page，--color-ink 生成 text-ink。background-color: var(--color-accent)，引用的是变量，而不是写死的颜色。.theme-street { ... }：DAY 09 和 DAY 29 学过的 CSS 变量覆盖。只要某个元素或它的祖先有 theme-street 这个 class，里面的变量就换成街头的颜色，所有 bg-accent 自然都变成橙色。所以你的 React 代码几乎不用改：App 最外层还是 className={`theme-${theme} ...`}，只是以前的 var(--accent) 现在写成了 bg-accent。
为什么变量名要叫 page、ink、accent、card，而不是 brown、orange？因为它们描述的是“用途”而不是“颜色本身”：page 是页面底色，ink 是文字色，accent 是强调色，card 是卡片底色。同一个用途在不同世界里是不同的颜色，按用途起名，切换风格时才说得通。如果叫 brown，到了街头风格它其实是橙色，名字就骗人了。以后你给后台加新颜色，也按这个思路起名。
App 最外层还加了 transition-colors：背景色和文字色变化时有一个短暂的过渡动画，切换风格不会“啪”地一下跳变。这就是 DAY 09 学的 transition，只是写成了一个类。
还有一件事要提前知道：Tailwind 自带一套叫 Preflight 的基础样式，会把浏览器的默认样式清掉：h1、h2 和普通文字一样大，ul 没有圆点，按钮没有边框和背景。刚装好时你会觉得页面“变丑了”，这是正常的。它的目的是让所有样式都由你明确地写出来，不受浏览器默认值干扰。另外，v4 里按钮的鼠标指针默认是箭头而不是手型，官方给了一小段 CSS 可以改回手型，下午会加上。
风格按钮要根据“是否选中”显示不同样式。用 DAY 13 学的模板字符串加三元运算符：
<button
type="button"
className={`rounded-full px-4 py-2 text-sm ${
theme === world.slug ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
{world.name}
</button>公共部分（圆角、内边距、字号）写在前面，变化的部分由三元运算符二选一。这是 React 加 Tailwind 最常见的写法。
但有一种写法不能用：
// 错误：Tailwind 找不到这个类
const color = 'red'
<p className={`text-${color}-600`}>出错了</p>
// 正确：把完整的类名写出来
<p className={hasError ? 'text-red-600' : 'text-green-600'}>...</p>原因是：Tailwind 是在你写代码时扫描文件里的“完整单词”来决定生成哪些 CSS 的，它不会运行你的代码。text-${color}-600 在文件里只是一串拼不完整的字符，Tailwind 看不出你最终想要 text-red-600，就不会生成它。记住：类名必须完整地出现在代码里，可以二选一，不能拼接。
最后提醒一点：同一个元素上不要写两个互相冲突的类，比如 p-4 p-6。哪个生效不是看你写的先后顺序，而是看 Tailwind 生成的 CSS 顺序，结果很难预料。要改就把旧的删掉。
安装 Tailwind
先按 Ctrl + C 停掉正在运行的开发服务器，然后在项目根目录安装：
cd ~/code/dongge-react
npm install tailwindcss @tailwindcss/vitetailwindcss 和 @tailwindcss/vite 两项。配置 Vite 插件
把 vite.config.ts 改成上午第 2 节的样子：导入 tailwindcss，加进 plugins 数组。如果你的文件里 import 的顺序和上面不同，没关系，关键是多了 import tailwindcss from '@tailwindcss/vite' 和 tailwindcss()。
重写 index.css
把 src/index.css 的内容全部替换成下面这些。三个世界的颜色和 DAY 29 的一样，如果你用了自己的颜色，照着换：
dongge-react/src/index.css
@import "tailwindcss";
@theme {
--color-page: #f4f1ea;
--color-ink: #1f1d1a;
--color-accent: #6b4f2a;
--color-card: #ffffff;
}
@layer base {
button:not(:disabled),
[role="button"]:not(:disabled) {
cursor: pointer;
}
}
.theme-gentleman {
--color-page: #f4f1ea;
--color-ink: #1f1d1a;
--color-accent: #6b4f2a;
--color-card: #ffffff;
}
.theme-street {
--color-page: #141414;
--color-ink: #f5f5f5;
--color-accent: #ff5a1f;
--color-card: #242424;
}
.theme-thai {
--color-page: #fff4e0;
--color-ink: #2a1a10;
--color-accent: #c8102e;
--color-card: #ffffff;
}@layer base { ... } 那一段就是官方给的“让按钮恢复手型指针”的写法。
重启，确认 Tailwind 生效
npm run dev打开页面，你会发现标题变小了、列表的圆点没了，这说明 Preflight 已经生效。再临时给 Intro 里的 h1 加上官方示例的 class：className="text-3xl font-bold underline"，看到标题变大、变粗、有下划线，就说明 Tailwind 装好了。
改写头像、介绍、平台按钮、区块
dongge-react/src/components/Avatar.tsx
type AvatarProps = {
src: string
alt: string
size?: number
}
export default function Avatar({ src, alt, size = 96 }: AvatarProps) {
return (
<img
src={src}
alt={alt}
width={size}
height={size}
className="mx-auto aspect-square rounded-full object-cover shadow-md"
/>
)
}props 和 DAY 27 一样，只是 className 换了。aspect-square 保证头像永远是正方形再裁成圆形，即使原图不是正方形也不会变成椭圆。
dongge-react/src/components/Intro.tsx
type IntroProps = {
name: string
tagline: string
}
export default function Intro({ name, tagline }: IntroProps) {
return (
<div className="mt-4 text-center">
<h1 className="text-3xl font-bold">{name}</h1>
<p className="mt-2 opacity-80">{tagline}</p>
</div>
)
}dongge-react/src/components/PlatformButton.tsx
type PlatformButtonProps = {
name: string
url: string
color?: string
}
export default function PlatformButton({ name, url, color = '#1f2a2e' }: PlatformButtonProps) {
return (
<a
href={url}
target="_blank"
rel="noopener noreferrer"
style={{ borderColor: color }}
className="block rounded-xl border-2 bg-card px-6 py-3.5 text-center font-semibold transition hover:-translate-y-0.5"
>
{name}
</a>
)
}品牌色是从数据里来的，四个平台各不相同，没法提前写成 Tailwind 类（还记得上午第 7 节说的“不能拼接类名”吗），所以边框颜色继续用 DAY 27 的行内样式 style={{ borderColor: color }}。固定的样式用 Tailwind 类，来自数据的动态值用 style，这是两者配合的常见分工，DAY 31 的进度条宽度也是这样。
dongge-react/src/components/Section.tsx
import type { ReactNode } from 'react'
type SectionProps = {
title: string
children: ReactNode
}
export default function Section({ title, children }: SectionProps) {
return (
<section className="mt-12">
<h2 className="mb-4 text-xl font-bold">{title}</h2>
{children}
</section>
)
}每改一个文件，都在浏览器里看一眼效果，对照上午第 3 节的表格理解每个类的作用。
改写穿搭卡片和列表
dongge-react/src/components/LookCard.tsx
import type { Look } from '../types'
import { getWorldName } from '../data/worlds'
type LookCardProps = {
look: Look
}
export default function LookCard({ look }: LookCardProps) {
return (
<article className="rounded-2xl bg-card p-5 shadow-sm">
<p className="text-sm text-accent">{getWorldName(look.world)}</p>
<h3 className="mt-1 text-lg font-bold">{look.title}</h3>
<p className="mt-2 text-sm opacity-80">{look.description}</p>
</article>
)
}dongge-react/src/components/LookList.tsx
import type { Look } from '../types'
import LookCard from './LookCard'
type LookListProps = {
looks: Look[]
}
export default function LookList({ looks }: LookListProps) {
if (looks.length === 0) {
return (
<p className="rounded-2xl border border-dashed border-accent p-8 text-center opacity-80">
这里还没有穿搭，过几天再来看看。
</p>
)
}
return (
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
{looks.map((look) => (
<LookCard key={look.id} look={look} />
))}
</div>
)
}改写 App.tsx，去掉 App.css
dongge-react/src/App.tsx
import { useEffect, useState } from 'react'
import type { World } from './types'
import Avatar from './components/Avatar'
import Intro from './components/Intro'
import PlatformButton from './components/PlatformButton'
import Section from './components/Section'
import LookList from './components/LookList'
import MessageForm from './components/MessageForm'
import Quiz from './quiz/Quiz'
import { platforms } from './data/platforms'
import { worlds, getWorldName } from './data/worlds'
import { looks } from './data/looks'
type Filter = World | 'all'
const THEME_KEY = 'dongge-theme'
function getSavedTheme(): World {
const saved = localStorage.getItem(THEME_KEY)
if (saved === 'gentleman' || saved === 'street' || saved === 'thai') {
return saved
}
return 'gentleman'
}
export default function App() {
const [theme, setTheme] = useState<World>(getSavedTheme)
const [filter, setFilter] = useState<Filter>('all')
useEffect(() => {
localStorage.setItem(THEME_KEY, theme)
}, [theme])
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])
const visibleLooks = filter === 'all' ? looks : looks.filter((look) => look.world === filter)
return (
<div className={`theme-${theme} min-h-screen bg-page text-ink transition-colors`}>
<main className="mx-auto max-w-3xl px-4 py-10">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<div className="mt-6 flex justify-center gap-2">
{worlds.map((world) => (
<button
key={world.slug}
type="button"
onClick={() => setTheme(world.slug)}
className={`rounded-full px-4 py-2 text-sm ${
theme === world.slug ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
{world.name}
</button>
))}
</div>
<nav aria-label="东哥的平台" className="mt-8 flex flex-col gap-3 md:flex-row md:justify-center">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} color={platform.color} />
))}
</nav>
<Section title="三个世界">
<ul className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
{worlds.map((world) => (
<li key={world.slug} className="rounded-2xl bg-card p-5 shadow-sm">
<p className="text-sm text-accent">{world.feeling}</p>
<h3 className="mt-1 text-lg font-bold">{world.name}</h3>
<p className="mt-2 text-sm opacity-80">{world.tagline}</p>
</li>
))}
</ul>
</Section>
<Section title="最近的穿搭">
<div className="mb-4 flex flex-wrap gap-2">
<button
type="button"
onClick={() => setFilter('all')}
className={`rounded-full px-4 py-2 text-sm ${
filter === 'all' ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
全部
</button>
{worlds.map((world) => (
<button
key={world.slug}
type="button"
onClick={() => setFilter(world.slug)}
className={`rounded-full px-4 py-2 text-sm ${
filter === world.slug ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
只看{world.name}
</button>
))}
</div>
<LookList looks={visibleLooks} />
</Section>
<Section title="给东哥留言">
<MessageForm />
</Section>
<Section title="测一测">
<Quiz />
</Section>
</main>
</div>
)
}和昨天相比，逻辑一行没变，只是：删掉了 import './App.css'；最外层的 app class 换成了 min-h-screen bg-page text-ink；所有 className 都换成了 Tailwind 类。
改写留言表单的样式
MessageForm.tsx 里 handleSubmit 等逻辑都不动，只把两个 return 换成下面的样子：
dongge-react/src/components/MessageForm.tsx（两个 return 部分）
if (sent) {
return (
<div className="rounded-2xl bg-card p-6 text-center shadow-sm">
<p>收到了，谢谢你的留言。</p>
<button
type="button"
onClick={() => setSent(false)}
className="mt-4 rounded-full bg-accent px-6 py-3 font-medium text-white transition hover:opacity-90"
>
再写一条
</button>
</div>
)
}
return (
<form onSubmit={handleSubmit} className="flex flex-col gap-2">
<label htmlFor="nickname" className="text-sm font-medium">
你的昵称（可以不填）
</label>
<input
id="nickname"
value={nickname}
onChange={(event) => setNickname(event.target.value)}
maxLength={20}
className="rounded-xl border border-ink/20 bg-card px-4 py-3 focus:border-accent"
/>
<label htmlFor="content" className="mt-2 text-sm font-medium">
想对东哥说的话
</label>
<textarea
id="content"
rows={4}
value={content}
onChange={(event) => setContent(event.target.value)}
className="rounded-xl border border-ink/20 bg-card px-4 py-3 focus:border-accent"
/>
<p className={`text-right text-sm ${content.length > MAX_LENGTH ? 'text-red-600' : 'opacity-70'}`}>
{content.length} / {MAX_LENGTH}
</p>
{error && <p className="text-sm text-red-600">{error}</p>}
<button
type="submit"
className="mt-2 rounded-full bg-accent px-6 py-3 font-medium text-white transition hover:opacity-90"
>
发送
</button>
</form>
)注意字数统计那一行：超过 200 字时变红，这就是“完整类名二选一”的写法。border-ink/20 是 20% 不透明的文字色，在深色和浅色风格下都能看清边框。
自己改写测试小游戏的四个组件
这一步请你先自己动手：QuizStart、ProgressBar、QuestionCard、ResultCard 里的 className 都还是旧的，参考前面几个组件的写法，把它们改成 Tailwind。改完再展开下面的参考答案对照。
dongge-react/src/quiz/QuizStart.tsx
return (
<div className="rounded-2xl bg-card p-6 text-center shadow-sm">
<h3 className="text-xl font-bold">你现在最需要哪个东哥？</h3>
<p className="mt-2 opacity-80">{total} 道题，一分钟做完。</p>
<button
type="button"
onClick={onStart}
className="mt-6 rounded-full bg-accent px-8 py-3 font-medium text-white transition hover:opacity-90"
>
开始
</button>
</div>
)dongge-react/src/quiz/ProgressBar.tsx
return (
<div className="mb-4">
<p className="mb-2 text-sm opacity-80">
第 {current} / {total} 题
</p>
<div className="h-2 overflow-hidden rounded-full bg-ink/10">
<div className="h-full bg-accent transition-all duration-300" style={{ width: `${percent}%` }} />
</div>
</div>
)dongge-react/src/quiz/QuestionCard.tsx
return (
<div className="rounded-2xl bg-card p-6 shadow-sm">
<h3 className="text-lg font-bold">{question.text}</h3>
<div className="mt-4 flex flex-col gap-3">
{question.options.map((option) => (
<button
key={option.text}
type="button"
onClick={() => onAnswer(option.world)}
className="rounded-xl border border-accent px-4 py-3 text-left transition hover:bg-accent hover:text-white"
>
{option.text}
</button>
))}
</div>
</div>
)dongge-react/src/quiz/ResultCard.tsx
return (
<div className="rounded-2xl bg-card p-6 text-center shadow-sm">
<p className="opacity-80">你最需要的是</p>
<p className="my-2 text-4xl font-bold text-accent">{result.name}</p>
<p className="text-sm font-medium">他给你的是：{result.feeling}</p>
<p className="mt-4 text-lg leading-relaxed">{result.summary}</p>
<p className="mt-2 text-sm leading-relaxed opacity-90">{result.detail}</p>
{outcome.topWorlds.length > 1 && (
<p className="mt-4 text-sm opacity-80">
你在{tieNames}之间打了个平手，按你最后的选择，结果算作{result.label}。
</p>
)}
<p className="mt-4 text-sm">{result.recommend}</p>
<button
type="button"
onClick={onRestart}
className="mt-6 rounded-full bg-accent px-8 py-3 font-medium text-white transition hover:opacity-90"
>
再测一次
</button>
</div>
)Quiz.tsx 里最外层的 className="quiz" 可以直接删掉，它现在没有对应的样式。
删除 App.css，全面检查
确认 App.tsx 里已经没有 import './App.css'，然后删除文件：
rm src/App.css在终端里搜一下还有没有漏掉的旧 class（比如 look-card、switcher、progress-fill）：
grep -rnE "look-card|switcher|filters|progress-fill|message-form" src用手机模拟模式检查响应式
在开发者工具里点左上角的手机图标（或按 Cmd + Shift + M）打开设备模拟，把宽度分别调到 375、768、1024 像素，观察：375 时平台按钮竖排、穿搭一列；768 时平台按钮横排、穿搭两列；1024 时穿搭三列。
请 Claude 审查，然后提交
把 App.tsx 和 index.css 发给 Claude，用“问 Claude”的第一条提示词请它审查，自己决定改什么。然后提交：
git add .
git commit -m "DAY 32 改用 Tailwind CSS v4"明天开始做新官网：首页、三个世界、链接页、测试入口。今天写好的组件，会在好几个页面里复用。
tailwindcss()；index.css 第一行是不是 @import "tailwindcss";；main.tsx 有没有导入 index.css。改完配置文件后要停掉开发服务器重新运行 npm run dev。bg-${color}-500 这样的拼接。Tailwind 只认代码里完整出现的类名，改成用三元运算符在几个完整类名之间选一个。text-3xl font-bold。--color-accent（必须以 --color- 开头），以及最外层 div 的 className 里有没有 theme-${theme}。cd ~/code/dongge-react 后重新运行 npm install tailwindcss @tailwindcss/vite。Tailwind 的 md: 前缀是什么意思？
md: 表示“当屏幕宽度大于等于 48rem（768px）时，这个类才生效”，相当于包了一层 @media (width >= 48rem) 的媒体查询。Tailwind 是手机优先的：不带前缀的类在所有屏幕上生效，是手机版的样式；带 md: 的类从平板宽度开始往上覆盖它。比如 flex-col md:flex-row 就是手机上竖排、768px 及以上横排。它不是“只在中等屏幕上生效”，在更大的电脑屏幕上也生效，除非被 lg: 等更大的前缀覆盖。
为什么 className={`bg-${world}-500`} 这种写法在 Tailwind 里不生效？应该怎么写？
Tailwind 是在构建时扫描源代码里完整出现的类名来生成 CSS 的，它不运行你的代码，看不到拼接后的结果。bg-${world}-500 在文件里不是一个完整的类名，所以对应的 CSS 根本没有生成。应该把完整的类名写出来，用条件在它们之间选择，比如 {isActive ? 'bg-accent text-white' : 'border border-accent'}；如果是按世界切换颜色，就像今天这样用 CSS 变量加 theme-xxx class 来实现。
你的按钮写的是 bg-accent，并没有写三个世界的颜色。为什么切换风格时它会变色？
index.css 的 @theme 里定义了 --color-accent，Tailwind 据此生成了 bg-accent 类，它的 CSS 是 background-color: var(--color-accent)，引用的是变量。App 最外层 div 带着 theme-street 之类的 class，index.css 里 .theme-street 重新定义了 --color-accent。CSS 变量会被子元素继承，所以里面所有 bg-accent 读到的都是街头的橙色。切换风格时 React 只改了最外层的 class，颜色就全部跟着变了。
text-sm md:text-base lg:text-lg 在 375px、800px、1200px 三种宽度下分别是什么字号，再告诉我对不对。pages/、components/ 文件夹组织代码。到昨天为止，你的 App.tsx 是一个很长的页面：头像、介绍、风格切换、平台按钮、三个世界、穿搭、留言、测试，全都从上往下排着。作为“链接主页”它够用，但作为你的官网，它有点像把客厅、卧室、厨房的东西全堆在一个房间里。
先站在粉丝的角度想一想她们是怎么来的：在小红书或 TikTok 刷到你的视频，点进主页，看到简介里的链接，点进来。这时她心里的问题可能是“这人是谁”“他还有什么内容”“他在别的平台叫什么”，也可能只是想玩一下测试。不同的问题，应该去不同的地方找答案。
所以今天要做的第一件事不是写代码，而是规划：网站有哪几页，每一页只负责回答一个主要问题。这就是“一页一个主要目的”的原则。目的清楚了，每页放什么、不放什么就好决定。
这种“决定网站分几页、每页放什么、页面之间怎么跳转”的工作，有一个专门的名字叫信息架构。听起来很专业，其实就是你装修房子前先画户型图：哪里是客厅、哪里是卧室、门开在哪。户型定好了再买家具（写组件），比买了一堆家具再想往哪摆要省事得多。今天上午的大部分时间，你都在画户型图。
按大纲，新官网有四个页面：
| 页面 | 回答粉丝的什么问题 | 放什么 |
|---|---|---|
| 首页 | 这人是谁？ | 头像、名字、一句话人设、三个世界的入口、测试和链接页的入口 |
| 三个世界 | 他平时是什么样的？ | 三个世界的卡片、全部穿搭，可以按世界筛选 |
| 链接页 | 在别的平台怎么找到他？ | 四个平台按钮、风格切换、给东哥留言 |
| 测一测 | 我最需要哪个他？ | 测试小游戏 |
几个取舍值得说一说：
明天你还会加一种页面：每个世界自己的详情页。今天先把这四页搭起来。
页面定下来后，把每一页拆成组件，画成一棵树。画树的目的有两个：一是看清楚哪些组件在多个页面里重复出现，它们应该写成通用组件；二是看清楚每份数据需要被哪些组件用到，从而决定 state 放在哪一层。
App state：page、theme
├── NavBar props：current、onNavigate
└── main（根据 page 只显示下面其中一页）
├── HomePage props：onNavigate
│ ├── Avatar
│ ├── Intro
│ └── Section（三个世界）
│ └── WorldCard × 3
├── WorldsPage state：filter
│ ├── WorldCard × 3
│ └── Section（穿搭）
│ └── LookList
│ └── LookCard × 6
├── LinksPage props：theme、onThemeChange
│ ├── Avatar
│ ├── Intro
│ ├── ThemeSwitcher props：value、onChange
│ ├── PlatformButton × 4
│ └── Section（给东哥留言）
│ └── MessageForm state：nickname、content、error、sent
└── QuizPage
└── Quiz state：started、answers从这棵树里能读出很多信息：
如果你不知道从哪下手，可以按这四步画：
这棵树不必一次画对。先画一版，写代码时发现不合适再改，这很正常。DAY 31 你让 Claude 在 Plan 模式出过组件树，今天换过来：你先画，再请 Claude 审查。
组件多了以后，全放在 components/ 里会很难找。常见的做法是按“角色”分文件夹：
src/
├── pages/ 页面组件：一个文件对应网站的一页
│ ├── HomePage.tsx
│ ├── WorldsPage.tsx
│ ├── LinksPage.tsx
│ └── QuizPage.tsx
├── components/ 通用组件：可以在多个页面里复用
│ ├── Avatar.tsx、Intro.tsx、Section.tsx、PlatformButton.tsx
│ ├── LookCard.tsx、LookList.tsx、MessageForm.tsx
│ └── NavBar.tsx、WorldCard.tsx、ThemeSwitcher.tsx（今天新建）
├── quiz/ 测试小游戏自己的一组组件
├── data/ 数据：platforms、worlds、looks
└── types.ts 类型页面组件的特点是：它代表网站的一整页，负责“把哪些通用组件按什么顺序摆在一起”，以及持有只属于这一页的 state。它一般不会在别处复用，名字统一以 Page 结尾，一眼就能认出来。
通用组件的特点是：它不关心自己在哪一页，只根据 props 显示内容。LookList 不知道自己是在三个世界页还是明天的详情页，给它什么穿搭，它就显示什么。
判断一个组件放哪个文件夹，问自己一句：“换一个页面，它还能用吗？”能，就放 components；它就是那一页本身，就放 pages。
命名上继续保持你 DAY 27 以来的习惯：一个文件一个组件，文件名和组件名完全一样，首字母大写，用 export default 导出。数据和类型文件用小写开头（worlds.ts、types.ts），因为它们导出的不是组件。这样在 VS Code 左边的文件列表里，一眼就能分出哪些是组件、哪些是数据。
DAY 31 学的状态提升，今天要反过来用一次。昨天 App 里有两个 state：theme（风格）和 filter（穿搭筛选）。拆成多个页面后，它们应该各自放在哪？还是用那个方法：找出所有需要它的组件，放在它们最近的共同父组件里。
有一个副作用你要知道：页面切换时，离开的页面组件会从页面上移除，它的 state 也就没了。你在三个世界页选了“只看街头”，切到首页再切回来，筛选会回到“全部”。对筛选来说这完全可以接受。但如果某个 state 必须在切换页面后保留，比如风格，它就必须放在不会被移除的地方，也就是 App。这又是 DAY 29 说的“state 跟着组件走”。
LinksPage 接收 theme 却自己不用、只是转交给 ThemeSwitcher，这种“一层层往下传”的写法叫 props 逐层传递。只传一两层完全没问题，直观又好查。以后项目大了、要传五六层时，才需要别的办法，现在不用担心。
四个页面组件写好后，怎么在它们之间切换？今天先用你已经会的东西：一个 state 记住“当前是哪一页”，再用条件渲染显示对应的页面。
dongge-react/src/types.ts（新增）
export type Page = 'home' | 'worlds' | 'links' | 'quiz'dongge-react/src/App.tsx（片段）
const [page, setPage] = useState<Page>('home')
<NavBar current={page} onNavigate={setPage} />
<main>
{page === 'home' && <HomePage onNavigate={setPage} />}
{page === 'worlds' && <WorldsPage />}
{page === 'links' && <LinksPage theme={theme} onThemeChange={setTheme} />}
{page === 'quiz' && <QuizPage />}
</main>逐行解释：Page 是一个字面量联合类型，页面只能是这四个之一。page 这个 state 记住当前页。NavBar 拿到当前页用来高亮按钮，拿到 setPage 用来在点击时切换。&& 条件渲染保证同一时间只显示一个页面。注意 onNavigate={setPage} 直接把 set 函数当回调传下去，因为它本身就是一个“接收一个 Page 参数”的函数，类型正好对得上。
这个方案能用，但写完你马上会发现它的问题：
localhost:5173/。这些问题不是你写错了，而是“用 state 切换页面”这个思路本身的局限。真正的网站，每一页都应该有自己的网址。明天你会学 React Router，用它把 page 这个 state 换成真正的网址，上面四个问题一次解决。今天先亲身体会一下这些不方便，明天会更明白路由为什么存在。
你可能会觉得：既然明天要换掉，今天何必写？因为明天真正要换掉的只有 App 里那几行切换逻辑和导航按钮的写法。四个页面组件、组件树、state 的分布、文件夹结构，全部原样保留。今天把“拆页面”这件事单独做完，明天就可以专心学路由，一次只学一件新东西。
讲了这么多复用，也要提醒一句：复用是为了少写重复代码，不是为了让一个组件包打天下。
看今天的 WorldCard。它要在首页和三个世界页显示，两处长得一样，所以做成一个组件，给一个 world prop 就够了。三张卡片颜色不同，也不需要加 color、background 之类的 props，因为用 theme-${world.slug} 这个 class 就解决了，数据本身已经说明了它属于哪个世界。
新手常犯的错是“预判未来”：担心以后某个页面需要大一点的卡片、需要隐藏标语、需要换个圆角，于是提前给组件加上七八个可选的 props。结果组件越来越难读，而那些“以后”往往根本不会来。更好的做法是：先按现在的需求写，等真的出现第二种用法时再改。到那时你手里有具体的例子，改出来的设计也更合理。
判断要不要抽成组件，也有一个简单的标准：同样的一段 JSX 出现了两次以上，或者一段 JSX 长到让所在的文件难以阅读，就值得抽出来。只出现一次、也不长的东西，留在页面组件里就好。
先画自己的组件树，请 Claude 审查
不看上午第 3 节的图，在笔记里自己画一遍整站组件树，标出每个 state 在哪、每个组件有哪些 props。然后把它发给 Claude（提示词见“问 Claude”第一条）。对照 Claude 的意见和课件的图，确定你要用的版本。
新建文件夹，添加 Page 类型
cd ~/code/dongge-react
mkdir -p src/pages在 src/types.ts 末尾加上 export type Page = 'home' | 'worlds' | 'links' | 'quiz'。
新建 WorldCard：每张卡片穿着自己世界的颜色
dongge-react/src/components/WorldCard.tsx
import type { WorldInfo } from '../types'
type WorldCardProps = {
world: WorldInfo
}
export default function WorldCard({ world }: WorldCardProps) {
return (
<div className={`theme-${world.slug} rounded-2xl bg-card p-6 text-ink shadow-sm`}>
<p className="text-sm text-accent">{world.feeling}</p>
<h3 className="mt-1 text-2xl font-bold">{world.name}</h3>
<p className="mt-2 text-sm opacity-80">{world.tagline}</p>
</div>
)
}注意第一个 class：theme-${world.slug}。昨天的 CSS 变量在这里又派上用场：街头卡片内部的 --color-card 被换成了深色，泰风卡片的 --color-accent 被换成了红色。不管整站是什么风格，三张卡片永远各是各的颜色。一个组件、一份代码，三种样子。
新建 ThemeSwitcher：把风格按钮抽成组件
dongge-react/src/components/ThemeSwitcher.tsx
import type { World } from '../types'
import { worlds } from '../data/worlds'
type ThemeSwitcherProps = {
value: World
onChange: (world: World) => void
}
export default function ThemeSwitcher({ value, onChange }: ThemeSwitcherProps) {
return (
<div className="flex justify-center gap-2">
{worlds.map((world) => (
<button
key={world.slug}
type="button"
onClick={() => onChange(world.slug)}
className={`rounded-full px-4 py-2 text-sm ${
value === world.slug ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
{world.name}
</button>
))}
</div>
)
}这就是原来 App 里那排按钮，只是 theme 换成了 props 里的 value，setTheme 换成了 onChange。value 加 onChange 这对名字，和表单输入框的写法一样，别人一看就知道它是一个“受控”的选择器。
新建 NavBar：导航栏
dongge-react/src/components/NavBar.tsx
import type { Page } from '../types'
type NavBarProps = {
current: Page
onNavigate: (page: Page) => void
}
const items: { page: Page; label: string }[] = [
{ page: 'home', label: '首页' },
{ page: 'worlds', label: '三个世界' },
{ page: 'links', label: '链接' },
{ page: 'quiz', label: '测一测' },
]
export default function NavBar({ current, onNavigate }: NavBarProps) {
return (
<nav aria-label="主导航" className="flex gap-1 overflow-x-auto py-4">
{items.map((item) => (
<button
key={item.page}
type="button"
onClick={() => onNavigate(item.page)}
className={`shrink-0 rounded-full px-4 py-2 text-sm ${
current === item.page ? 'bg-accent text-white' : 'hover:bg-card'
}`}
>
{item.label}
</button>
))}
</nav>
)
}{ page: Page; label: string }[] 是直接写在变量后面的类型：一个数组，每一项有 page 和 label 两个字段。只在这个文件里用，所以没有单独起名字。overflow-x-auto 让导航在很窄的手机上可以左右滑动，shrink-0 防止按钮被挤扁。aria-label="主导航" 给这个 nav 起个名字：链接页里平台按钮外面也是一个 nav（叫“东哥的平台”），读屏软件靠名字区分它们。
新建首页
dongge-react/src/pages/HomePage.tsx
import type { Page } from '../types'
import Avatar from '../components/Avatar'
import Intro from '../components/Intro'
import Section from '../components/Section'
import WorldCard from '../components/WorldCard'
import { worlds } from '../data/worlds'
type HomePageProps = {
onNavigate: (page: Page) => void
}
export default function HomePage({ onNavigate }: HomePageProps) {
return (
<div className="py-8">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<div className="mt-8 flex flex-col gap-3 sm:flex-row sm:justify-center">
<button
type="button"
onClick={() => onNavigate('quiz')}
className="rounded-full bg-accent px-6 py-3 font-medium text-white transition hover:opacity-90"
>
测一测你最需要哪个东哥
</button>
<button
type="button"
onClick={() => onNavigate('links')}
className="rounded-full border border-accent px-6 py-3 font-medium text-accent"
>
在这些平台找到我
</button>
</div>
<Section title="三个世界">
<div className="grid gap-4 md:grid-cols-3">
{worlds.map((world) => (
<WorldCard key={world.slug} world={world} />
))}
</div>
</Section>
</div>
)
}首页的两个按钮要跳到别的页面，所以它也需要 onNavigate。注意 import 的路径：pages 文件夹里的文件要用 ../components/ 才能找到组件。
新建三个世界页，把筛选搬进来
dongge-react/src/pages/WorldsPage.tsx
import { useState } from 'react'
import type { World } from '../types'
import Section from '../components/Section'
import WorldCard from '../components/WorldCard'
import LookList from '../components/LookList'
import { worlds } from '../data/worlds'
import { looks } from '../data/looks'
type Filter = World | 'all'
export default function WorldsPage() {
const [filter, setFilter] = useState<Filter>('all')
const visibleLooks = filter === 'all' ? looks : looks.filter((look) => look.world === filter)
return (
<div className="py-8">
<h1 className="text-3xl font-bold">三个世界</h1>
<p className="mt-2 opacity-80">绅士、街头、泰风，是我生活里的三个样子。</p>
<div className="mt-6 grid gap-4 md:grid-cols-3">
{worlds.map((world) => (
<WorldCard key={world.slug} world={world} />
))}
</div>
<Section title="穿搭">
<div className="mb-4 flex flex-wrap gap-2">
<button
type="button"
onClick={() => setFilter('all')}
className={`rounded-full px-4 py-2 text-sm ${
filter === 'all' ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
全部
</button>
{worlds.map((world) => (
<button
key={world.slug}
type="button"
onClick={() => setFilter(world.slug)}
className={`rounded-full px-4 py-2 text-sm ${
filter === world.slug ? 'bg-accent text-white' : 'border border-accent text-accent'
}`}
>
只看{world.name}
</button>
))}
</div>
<LookList looks={visibleLooks} />
</Section>
</div>
)
}filter 的 state、Filter 类型、visibleLooks 的计算、筛选按钮，都是从昨天的 App.tsx 原样搬过来的。
新建链接页和测试页
dongge-react/src/pages/LinksPage.tsx
import type { World } from '../types'
import Avatar from '../components/Avatar'
import Intro from '../components/Intro'
import PlatformButton from '../components/PlatformButton'
import Section from '../components/Section'
import ThemeSwitcher from '../components/ThemeSwitcher'
import MessageForm from '../components/MessageForm'
import { platforms } from '../data/platforms'
type LinksPageProps = {
theme: World
onThemeChange: (world: World) => void
}
export default function LinksPage({ theme, onThemeChange }: LinksPageProps) {
return (
<div className="mx-auto max-w-xl py-8">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<div className="mt-6">
<ThemeSwitcher value={theme} onChange={onThemeChange} />
</div>
<nav aria-label="东哥的平台" className="mt-8 flex flex-col gap-3">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} color={platform.color} />
))}
</nav>
<Section title="给东哥留言">
<MessageForm />
</Section>
</div>
)
}链接页用 max-w-xl 收窄，平台按钮在任何屏幕上都竖着排，和各平台常见的“链接主页”一样，手机上一眼就能看到全部按钮。
dongge-react/src/pages/QuizPage.tsx
import Quiz from '../quiz/Quiz'
export default function QuizPage() {
return (
<div className="mx-auto max-w-xl py-8">
<h1 className="text-3xl font-bold">测一测</h1>
<p className="mt-2 opacity-80">选最接近你的答案，不用想太久。</p>
<div className="mt-6">
<Quiz />
</div>
</div>
)
}重写 App.tsx：只负责“外框”和切换
dongge-react/src/App.tsx
import { useEffect, useState } from 'react'
import type { Page, World } from './types'
import NavBar from './components/NavBar'
import HomePage from './pages/HomePage'
import WorldsPage from './pages/WorldsPage'
import LinksPage from './pages/LinksPage'
import QuizPage from './pages/QuizPage'
import { getWorldName } from './data/worlds'
const THEME_KEY = 'dongge-theme'
function getSavedTheme(): World {
const saved = localStorage.getItem(THEME_KEY)
if (saved === 'gentleman' || saved === 'street' || saved === 'thai') {
return saved
}
return 'gentleman'
}
export default function App() {
const [page, setPage] = useState<Page>('home')
const [theme, setTheme] = useState<World>(getSavedTheme)
useEffect(() => {
localStorage.setItem(THEME_KEY, theme)
}, [theme])
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])
return (
<div className={`theme-${theme} min-h-screen bg-page text-ink transition-colors`}>
<div className="mx-auto max-w-4xl px-4">
<NavBar current={page} onNavigate={setPage} />
<main className="pb-16">
{page === 'home' && <HomePage onNavigate={setPage} />}
{page === 'worlds' && <WorldsPage />}
{page === 'links' && <LinksPage theme={theme} onThemeChange={setTheme} />}
{page === 'quiz' && <QuizPage />}
</main>
</div>
</div>
)
}对比昨天的 App.tsx：几十行的页面内容都搬进了 pages，App 只剩下三件事：管风格、管当前页、摆好导航和页面区域。import 也少了很多，多余的 import 要删干净，否则 npm run build 时 TypeScript 会报“声明了但从未使用”。
亲身体验这个方案的局限
依次做三件事，把现象记在笔记里：切到“测一测”，看地址栏有没有变化；在测试页按 Cmd + R 刷新，看回到了哪一页；从首页点到“三个世界”，再按浏览器的后退键，看发生了什么。
最后在终端运行一次类型检查和构建，确认没有遗漏的错误：
npm run buildnpm run build 没有报错，最后显示 built in 多少秒。在手机模拟模式下逐页检查
打开开发者工具的设备模拟，宽度调到 375 像素，四个页面挨个看：导航能不能左右滑动、首页的两个按钮是不是竖排、世界卡片是不是一列、链接页的平台按钮是不是好点。发现的问题列成清单，能改的当场改。
请 Claude 审查，然后提交
把 App.tsx 和 pages 文件夹里的四个文件发给 Claude，用“问 Claude”的第二条提示词。自己决定改哪些，改完提交：
git add .
git commit -m "DAY 33 新官网结构：四个页面和导航"'../components/Avatar'。theme-${world.slug}，或者模板字符串写成了普通引号，${} 没有被替换。onNavigate={setPage}。TypeScript 通常会提前报红，留意编辑器提示。哪些组件在多个页面复用了？
Avatar 和 Intro 在首页和链接页复用；WorldCard 在首页和三个世界页复用；Section 在首页、三个世界页、链接页复用。另外 LookList 和 LookCard 虽然今天只在三个世界页出现，但它们只依赖 props，明天做世界详情页时也会复用。它们能复用的原因是：只根据 props 显示内容，不关心自己在哪个页面、数据从哪里来。
为什么 theme 留在了 App，而 filter 从 App 挪进了 WorldsPage？
theme 决定整站配色，App 最外层要用它，切换按钮又在 LinksPage 里，两者最近的共同父组件是 App，而且风格要在切换页面后保留，必须放在不会被移除的 App 里。filter 只有三个世界页用到，放在 App 会让 App 管一件与它无关的事，还要把 state 一层层传下去；放进 WorldsPage 就是“谁用谁管”。代价是离开这一页再回来筛选会重置，对筛选来说可以接受。
今天用 state 切换页面，你发现了哪些问题？
第一，网址不会变，地址栏一直是首页的地址；第二，刷新后 page 回到初始值，总是回到首页；第三，没法把某一页（比如测试页）的链接单独分享出去或放进平台简介；第四，浏览器的后退、前进键不能在页面之间切换。根本原因是“当前页”只存在内存里的 state 中，而不在网址里。明天用 React Router 让每一页都有自己的网址来解决。
/world/:id 和 useParams，让三个世界共用一个详情页组件。src/data/worlds.ts 这一个文件，刷新、分享、后退都正常。昨天你用一个 page state 在四个页面之间切换，并亲眼看到了它的问题：网址不变、刷新回首页、没法分享某一页、后退键没用。这四个问题其实是同一个原因：“现在在哪一页”只记在内存里，而没有记在网址里。
网址就像门牌号。别人知道了门牌号，就能直接找到那户人家；你把门牌号写在名片上，谁都能按着找来。你希望在小红书简介里放 你的网址/links，在视频评论区回复“测试在这里：你的网址/quiz”，粉丝点进来就直接到那一页。这就要求：每个页面都有自己的网址，打开网址就显示对应的页面。
今天要学的 React Router，就是专门做这件事的库。它会把昨天的 page state 换成真正的网址，而你写好的四个页面组件一行都不用改。
回想 DAY 03 学的“一次网页访问的全过程”：浏览器向服务器请求一个网址，服务器返回一个 HTML 文件。传统的多页面网站，每个网址对应服务器上一个不同的 HTML 文件，比如 /about.html，每次点链接都要向服务器要一个新页面，整页重新加载。
你的 React 项目不一样。打开项目根目录的 index.html 看看（昨天运行过 npm run build 的话，dist 文件夹里也一样），整个网站只有一个 HTML 文件，里面几乎是空的，只有一个 <div id="root">。所有页面都是 JavaScript 在浏览器里画出来的。这种网站叫单页应用（Single Page Application，简称 SPA）。
单页应用要实现“不同网址显示不同页面”，就靠前端路由：
/quiz，在一张“对照表”里查到应该显示 QuizPage，就把它画出来。打个比方：传统网站像一栋楼，每个房间一个门牌，你要换房间就得出门、上楼、开另一扇门。单页应用像一个大厅里的一块大屏幕，你按遥控器，屏幕换一个画面，同时门口的门牌号也跟着换，但你始终站在同一个大厅里。React Router 就是那个遥控器加门牌系统。
React Router 是 React 最常用的路由库。它的新版本（v7 起）统一只用一个包，名字就叫 react-router。网上很多旧教程写的是 react-router-dom，那是以前的包名，新版已经不需要，最新的 v8 更是把它彻底去掉了。写这份课件时官网最新版本是 v8，我们用的写法在 v7 和 v8 里都一样。
React Router 提供三种用法，官网叫三种“模式”：
你现在只需要“不同网址显示不同页面”，所以选声明式模式。数据加载这类需求，DAY 37 起你会在 Next.js 里用另一套方式学。
安装只有一行：
npm i react-router然后在 main.tsx 里用 BrowserRouter 把整个 App 包起来：
dongge-react/src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BrowserRouter } from 'react-router'
import './index.css'
import App from './App.tsx'
createRoot(document.getElementById('root')!).render(
<StrictMode>
<BrowserRouter>
<App />
</BrowserRouter>
</StrictMode>,
)逐行解释：
import { BrowserRouter } from 'react-router'：从 react-router 包里导入 BrowserRouter。<BrowserRouter>：它负责监听浏览器的网址，并把“当前网址是什么”提供给里面所有的组件。只有被它包在里面的组件，才能使用路由的功能，所以放在最外层。document.getElementById('root')!：这是 Vite 模板原本就有的写法。末尾的 ! 是告诉 TypeScript“我保证这个元素一定存在，不会是 null”。node -v 查看。具体要求以官网为准。dongge-react/src/App.tsx（片段）
import { Route, Routes } from 'react-router'
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/worlds" element={<WorldsPage />} />
<Route path="/world/:id" element={<WorldDetailPage />} />
<Route path="/links" element={<LinksPage theme={theme} onThemeChange={setTheme} />} />
<Route path="/quiz" element={<QuizPage />} />
</Routes>逐行解释：
<Route path="..." element={...} />：对照表的一行。path 是网址的路径部分（域名后面那一段），element 是这个网址要显示的组件，要写成 JSX 的形式 {<HomePage />}，props 照常传。<Routes>：把所有 Route 包起来。它会看当前网址，从里面挑出最匹配的那一行，只显示那一个 element，其他的都不显示。path="/"：只匹配首页 / 本身，不会因为 /quiz 也以斜杠开头就误匹配。path="/world/:id"：动态路由，第 6 节专门讲。对比昨天的写法：四行 {page === 'home' && ...} 变成了五行 Route，逻辑是一样的，“看某个值决定显示哪个页面”。区别只在于，昨天看的是内存里的 page，今天看的是地址栏里的网址。NavBar 和 Routes 是兄弟，NavBar 放在 Routes 外面，所以它在每个页面都会显示。
Route 的书写顺序不影响匹配结果。React Router 会给每一行打分，越具体的路径分越高。比如以后你加了一行 path="/world/new"，访问 /world/new 时它和 /world/:id 都能匹配，React Router 会选写死的、更具体的 /world/new，不管它写在前面还是后面。你可以按自己觉得好读的顺序排列，习惯上首页写在最前面。
如果当前网址在表里一行都匹配不上，比如 /abc，Routes 就什么都不显示。明天你会加一行“兜底”的路由，专门显示 404 页面。
有了网址，页面之间的跳转就要改成“跳到某个网址”。你可能会想用学了很久的 a 标签：<a href="/quiz">。它能用，但每次点击，浏览器都会向服务器重新请求整个网站：重新下载 HTML 和 JavaScript，React 从头启动一遍，内存里所有 state 都丢了。比如测试做到一半，点一下导航再点回来，进度就没了。
React Router 提供了 Link 组件：
import { Link } from 'react-router'
<Link to="/quiz">测一测你最需要哪个东哥</Link>Link 最终在页面上渲染的还是一个 <a href="/quiz">，所以右键“在新标签页打开”、读屏软件这些都照常工作。区别是它会拦下普通的点击，改用第 2 节说的 History API 切换网址，不刷新整页。属性从 href 换成了 to。
导航栏还需要一个额外的功能：高亮当前所在的页面。这时用 NavLink，它是“知道自己是否处于激活状态的 Link”：
import { NavLink } from 'react-router'
<NavLink
to="/quiz"
end
className={({ isActive }) => (isActive ? 'bg-accent text-white' : 'hover:bg-card')}
>
测一测
</NavLink>className 在这里不是字符串，而是一个函数。NavLink 调用它时会传进一个对象，里面的 isActive 告诉你“当前网址是不是这个链接指向的地方”，你根据它返回不同的类名。end：表示“网址必须完全一样才算激活”。如果首页的 to="/" 不加 end，任何以 / 开头的网址都会让它激活，首页按钮就永远亮着。一个简单的规则：跳到自己网站里的页面，用 Link 或 NavLink；跳到别的网站（比如小红书主页），继续用 a 标签，就像你的 PlatformButton 那样。
今天要给三个世界各做一个详情页：/world/gentleman、/world/street、/world/thai。你可能会想写三个组件 GentlemanPage、StreetPage、ThaiPage，再配三行 Route。但三个页面的结构完全一样：标题、一段介绍、穿搭标签、这个世界的穿搭列表，只是内容不同。
这正是 DAY 28 学的“数据是清单，组件是模板”：一个页面组件当模板，网址里的一部分当参数，由参数决定填进去什么数据。这就是动态路由：
<Route path="/world/:id" element={<WorldDetailPage />} />:id 前面的冒号表示“这一段是一个占位符，可以是任何值”。/world/street、/world/thai 都会匹配这一行，都显示 WorldDetailPage。那组件怎么知道现在是哪个世界？用 useParams：
dongge-react/src/pages/WorldDetailPage.tsx（片段）
import { useParams } from 'react-router'
import { getWorld } from '../data/worlds'
export default function WorldDetailPage() {
const { id } = useParams()
const world = getWorld(id)
if (!world) {
return <p>没有找到这个世界</p>
}
// 下面用 world.name、world.description 等渲染页面
}逐行解释：
useParams()：React Router 提供的 Hook，返回一个对象，里面是网址中所有占位符的值。访问 /world/street 时，它返回 { id: 'street' }。占位符叫什么名字，这里就用什么名字取。const { id } = ...：用 DAY 17 学的解构取出 id。它的类型是 string | undefined：TypeScript 不知道网址里会是什么，所以只能说“一个字符串，或者没有”。getWorld(id)：今天在 worlds.ts 里新加的一个小函数，用 DAY 16 学的 find 按 slug 查找，找不到就返回 undefined。它的参数类型写成 string | undefined，正好能直接接住 useParams 给的 id。if (!world)：网址是别人能随便改的。有人手动输入 /world/abc，getWorld 会返回 undefined。必须先处理“找不到”的情况，TypeScript 也会强制你这么做，否则后面的 world.name 会报错。一个组件，三个网址，三份内容。以后如果你多了第四个世界，只要在数据里加一项，详情页自动就有了，一行页面代码都不用写。
详情页需要比卡片更多的内容：一段介绍和这个世界的穿搭标签。这些都加进 src/data/worlds.ts，让它成为“三个世界”唯一的数据来源：首页的卡片、三个世界页、详情页，全都从这里读。（测试结果页的文案是 DAY 24 写的 results.ts，那是测试专用的内容，继续放在 quiz 文件夹里。）
先在类型里加两个字段：
export type WorldInfo = {
slug: World
name: string
feeling: string
tagline: string
description: string
outfit: string[]
}outfit: string[] 是一个字符串数组，比如 ['马甲', '白衬衫', '西裤', '皮鞋']，详情页用 map 把它渲染成一排小标签。改完类型后，worlds.ts 里三个对象会一起报红，提醒你每个世界都要补齐。这就是类型的好处：它不让你漏掉任何一个。
为什么坚持“一个文件”？想象数据分散在三个详情页组件里：哪天你想把“泰风”改名叫“泰拳”，就得在首页卡片、三个世界页、每个详情页里分别找、分别改，漏一个就前后不一致。集中在一处，改一次处处生效。DAY 42 以后，这份数据会搬进数据库，那时你只需要换掉“数据从哪来”，页面组件还是今天这些。
检查 Node 版本，安装 React Router
cd ~/code/dongge-react
node -v
npm i react-router如果安装时出现 EBADENGINE 警告，说明你的 Node 版本低于要求，先用你 DAY 01 安装 Node 的方式升级到最新的 LTS 版本，再重新安装。
react-router。在 main.tsx 里包上 BrowserRouter
把 src/main.tsx 改成上午第 3 节的样子，只多了一行 import 和包在 App 外面的 <BrowserRouter>。
改写 App.tsx：用 Routes 替换 page state
dongge-react/src/App.tsx
import { useEffect, useState } from 'react'
import { Route, Routes } from 'react-router'
import type { World } from './types'
import NavBar from './components/NavBar'
import HomePage from './pages/HomePage'
import WorldsPage from './pages/WorldsPage'
import WorldDetailPage from './pages/WorldDetailPage'
import LinksPage from './pages/LinksPage'
import QuizPage from './pages/QuizPage'
import { getWorldName } from './data/worlds'
const THEME_KEY = 'dongge-theme'
function getSavedTheme(): World {
const saved = localStorage.getItem(THEME_KEY)
if (saved === 'gentleman' || saved === 'street' || saved === 'thai') {
return saved
}
return 'gentleman'
}
export default function App() {
const [theme, setTheme] = useState<World>(getSavedTheme)
useEffect(() => {
localStorage.setItem(THEME_KEY, theme)
}, [theme])
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])
return (
<div className={`theme-${theme} min-h-screen bg-page text-ink transition-colors`}>
<div className="mx-auto max-w-4xl px-4">
<NavBar />
<main className="pb-16">
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/worlds" element={<WorldsPage />} />
<Route path="/world/:id" element={<WorldDetailPage />} />
<Route path="/links" element={<LinksPage theme={theme} onThemeChange={setTheme} />} />
<Route path="/quiz" element={<QuizPage />} />
</Routes>
</main>
</div>
</div>
)
}page state 和 Page 类型不再需要了：删掉 App 里的 useState<Page>，再打开 src/types.ts 删掉 export type Page = ... 那一行。WorldDetailPage 还没写，编辑器会报红，浏览器也会暂时显示一个找不到文件的错误，第 7 步写好它就恢复了。
改写 NavBar：用 NavLink
dongge-react/src/components/NavBar.tsx
import { NavLink } from 'react-router'
const items = [
{ to: '/', label: '首页' },
{ to: '/worlds', label: '三个世界' },
{ to: '/links', label: '链接' },
{ to: '/quiz', label: '测一测' },
]
export default function NavBar() {
return (
<nav aria-label="主导航" className="flex gap-1 overflow-x-auto py-4">
{items.map((item) => (
<NavLink
key={item.to}
to={item.to}
end
className={({ isActive }) =>
`shrink-0 rounded-full px-4 py-2 text-sm ${isActive ? 'bg-accent text-white' : 'hover:bg-card'}`
}
>
{item.label}
</NavLink>
))}
</nav>
)
}和昨天比，NavBar 不再需要任何 props：当前在哪一页，NavLink 自己从网址里知道。
改写首页：按钮换成 Link
dongge-react/src/pages/HomePage.tsx
import { Link } from 'react-router'
import Avatar from '../components/Avatar'
import Intro from '../components/Intro'
import Section from '../components/Section'
import WorldCard from '../components/WorldCard'
import { worlds } from '../data/worlds'
export default function HomePage() {
return (
<div className="py-8">
<Avatar src="/avatar.jpg" alt="三岁的东哥的头像" />
<Intro name="三岁的东哥" tagline="在外面是绅士、拳手、潮男，在你面前三岁。" />
<div className="mt-8 flex flex-col gap-3 sm:flex-row sm:justify-center">
<Link
to="/quiz"
className="rounded-full bg-accent px-6 py-3 text-center font-medium text-white transition hover:opacity-90"
>
测一测你最需要哪个东哥
</Link>
<Link
to="/links"
className="rounded-full border border-accent px-6 py-3 text-center font-medium text-accent"
>
在这些平台找到我
</Link>
</div>
<Section title="三个世界">
<div className="grid gap-4 md:grid-cols-3">
{worlds.map((world) => (
<WorldCard key={world.slug} world={world} />
))}
</div>
</Section>
</div>
)
}onNavigate 这个 prop 和 Page 类型的导入都删掉了。
扩充三个世界的数据
先按上午第 7 节在 src/types.ts 的 WorldInfo 里加上 description 和 outfit。然后把 src/data/worlds.ts 整个改成下面这样：数组里补上新字段，末尾新增一个 getWorld 函数。文案换成你自己真实的经历，守住“说事情不说情话”：
dongge-react/src/data/worlds.ts
import type { World, WorldInfo } from '../types'
export const worlds: WorldInfo[] = [
{
slug: 'gentleman',
name: '绅士',
feeling: '安全感',
tagline: '斯诺克台边，马甲、衬衫、皮鞋。',
description:
'周末常去球房打斯诺克。出杆前先把线路看清楚，不急。马甲和衬衫不是为了拍照，这项运动本来就讲究穿得体面。',
outfit: ['马甲', '白衬衫', '西裤', '皮鞋'],
},
{
slug: 'street',
name: '街头',
feeling: '心动',
tagline: 'BMX 和滑板，Baggy 裤配 Vans。',
description:
'骑 BMX，玩滑板，在公园里一待就是一下午。摔了拍拍土再来，新动作第一次落地的那一下最开心。',
outfit: ['Baggy 裤', 'Vans', 'Oversize T 恤', '棒球帽'],
},
{
slug: 'thai',
name: '泰风',
feeling: '被保护感',
tagline: '泰拳馆里，一条泰拳短裤。',
description: '练泰拳，也喜欢泰国的街头小吃和寺庙。训练时很认真，下了拳台说话很轻。',
outfit: ['泰拳短裤', '拳击绷带', '拳套', '背心'],
},
]
export function getWorld(slug: string | undefined): WorldInfo | undefined {
return worlds.find((world) => world.slug === slug)
}
export function getWorldName(slug: World): string {
const found = worlds.find((world) => world.slug === slug)
return found ? found.name : slug
}getWorldName 是 DAY 28 写的，保持不变。新的 getWorld 返回整个世界的信息而不只是名字，参数允许是 undefined，因为 useParams 取出来的 id 可能不存在。
写世界详情页
dongge-react/src/pages/WorldDetailPage.tsx
import { Link, useParams } from 'react-router'
import LookList from '../components/LookList'
import { getWorld } from '../data/worlds'
import { looks } from '../data/looks'
export default function WorldDetailPage() {
const { id } = useParams()
const world = getWorld(id)
if (!world) {
return (
<div className="py-16 text-center">
<h1 className="text-2xl font-bold">没有找到这个世界</h1>
<Link to="/worlds" className="mt-6 inline-block text-accent underline">
回到三个世界
</Link>
</div>
)
}
const worldLooks = looks.filter((look) => look.world === world.slug)
return (
<article className={`theme-${world.slug} mt-4 rounded-3xl bg-page p-6 text-ink shadow-sm md:p-10`}>
<p className="text-sm text-accent">给你的感觉：{world.feeling}</p>
<h1 className="mt-2 text-4xl font-bold">{world.name}</h1>
<p className="mt-4 max-w-2xl leading-relaxed">{world.description}</p>
<ul className="mt-6 flex flex-wrap gap-2">
{world.outfit.map((item) => (
<li key={item} className="rounded-full border border-accent px-3 py-1 text-sm">
{item}
</li>
))}
</ul>
<h2 className="mt-10 text-xl font-bold">{world.name}的穿搭</h2>
<div className="mt-4">
<LookList looks={worldLooks} />
</div>
<Link
to="/quiz"
className="mt-10 inline-block rounded-full bg-accent px-6 py-3 font-medium text-white transition hover:opacity-90"
>
测一测你最需要哪个东哥
</Link>
</article>
)
}注意最外层的 theme-${world.slug}：不管访客选的整站风格是什么，街头详情页永远是街头的配色。LookList 是 DAY 28 写的组件，这里第三次复用它，给它筛好的穿搭就行。
http://localhost:5173/world/street，看到深色的街头详情页和两套街头穿搭；改成 /world/thai，内容和颜色都变了；改成 /world/abc，看到“没有找到这个世界”。世界卡片变成可点击的链接
dongge-react/src/components/WorldCard.tsx
import { Link } from 'react-router'
import type { WorldInfo } from '../types'
type WorldCardProps = {
world: WorldInfo
}
export default function WorldCard({ world }: WorldCardProps) {
return (
<Link
to={`/world/${world.slug}`}
className={`theme-${world.slug} block rounded-2xl bg-card p-6 text-ink shadow-sm transition hover:-translate-y-1`}
>
<p className="text-sm text-accent">{world.feeling}</p>
<h3 className="mt-1 text-2xl font-bold">{world.name}</h3>
<p className="mt-2 text-sm opacity-80">{world.tagline}</p>
<p className="mt-4 text-sm font-medium text-accent">进入这个世界 →</p>
</Link>
)
}只改了一处：最外层的 div 换成 Link，加上 to 和 block（a 标签默认是行内元素，要让它像卡片一样占满一块）。首页和三个世界页因为复用了 WorldCard，两处的卡片同时变成了可点击的。
测试结果页加一个“去看看这个世界”
dongge-react/src/quiz/ResultCard.tsx
import { Link } from 'react-router'
import type { QuizOutcome } from '../types'
import { results } from './results'
type ResultCardProps = {
outcome: QuizOutcome
onRestart: () => void
}
export default function ResultCard({ outcome, onRestart }: ResultCardProps) {
const result = results[outcome.world]
const tieNames = outcome.topWorlds.map((world) => results[world].label).join('、')
return (
<div className="rounded-2xl bg-card p-6 text-center shadow-sm">
<p className="opacity-80">你最需要的是</p>
<p className="my-2 text-4xl font-bold text-accent">{result.name}</p>
<p className="text-sm font-medium">他给你的是：{result.feeling}</p>
<p className="mt-4 text-lg leading-relaxed">{result.summary}</p>
<p className="mt-2 text-sm leading-relaxed opacity-90">{result.detail}</p>
{outcome.topWorlds.length > 1 && (
<p className="mt-4 text-sm opacity-80">
你在{tieNames}之间打了个平手，按你最后的选择，结果算作{result.label}。
</p>
)}
<p className="mt-4 text-sm">{result.recommend}</p>
<div className="mt-6 flex flex-col gap-3 sm:flex-row sm:justify-center">
<Link
to={`/world/${outcome.world}`}
className="rounded-full border border-accent px-8 py-3 font-medium text-accent"
>
去看看{result.label}的世界
</Link>
<button
type="button"
onClick={onRestart}
className="rounded-full bg-accent px-8 py-3 font-medium text-white transition hover:opacity-90"
>
再测一次
</button>
</div>
</div>
)
}和昨天相比，只多了顶部的 Link 导入，以及最下面把“再测一次”和新的 Link 放进同一行。outcome.world 就是 gentleman、street、thai 之一，正好是详情页网址里需要的那一段。测完直接点进去，粉丝就能看到这个世界的介绍和穿搭。
验证昨天的四个问题都解决了
逐项检查：点导航，地址栏变成 /worlds、/links、/quiz；在 /quiz 刷新，仍然是测试页；从首页点到三个世界再点进街头，连按两次后退键，依次回到三个世界和首页；把 http://localhost:5173/links 复制到一个新标签页打开，直接就是链接页。
/abc，你会看到只有导航、下面一片空白，控制台有一条 No routes matched 的提示。这是明天要做的 404 页面。构建检查
npm run build请 Claude 审查，然后提交
把 main.tsx、App.tsx、NavBar.tsx、WorldDetailPage.tsx 发给 Claude，用“问 Claude”的第一条提示词。自己改完后提交：
git add .
git commit -m "DAY 34 React Router 和世界详情页"'react-router' 导入。end，任何网址都以 / 开头，它就一直被认为是激活的。<a href="/quiz">。站内跳转换成 <Link to="/quiz">。if (!world) 处理找不到的情况。为什么三个世界共用一个页面组件，而不是写三个页面？
三个世界的详情页结构完全一样（标题、介绍、穿搭标签、穿搭列表），只是数据不同。用动态路由 /world/:id，一个 WorldDetailPage 当模板，用 useParams 读出网址里的 id，再从 worlds.ts 里取对应的数据填进去。好处是：页面结构只写一次，改样式只改一处，三个页面永远保持一致；数据集中在一个文件，改文案不会漏；以后增加第四个世界，只需要在数据里加一项，不用新写页面和路由。写三个页面则是三份几乎相同的代码，改一处要改三遍，很容易不一致。
站内跳转为什么用 Link 而不是 a 标签？跳到小红书主页时呢？
a 标签会让浏览器向服务器重新请求整个页面，React 从头启动，内存中的 state（比如测试进度）全部丢失，速度也慢。Link 渲染出来仍是 a 标签，但会拦下点击，用 History API 修改网址并切换组件，不刷新整页。跳到小红书这种别的网站时，React Router 管不了，继续用普通 a 标签，并加 target="_blank" 和 rel="noopener noreferrer"。
在浏览器地址栏输入 http://localhost:5173/world/street 并回车，到页面显示出来，React Router 做了哪些事？
开发服务器返回唯一的 index.html 和 JavaScript；React 启动，BrowserRouter 读取当前网址 /world/street；Routes 在所有 Route 里找到最匹配的 /world/:id，渲染 WorldDetailPage，并记下 id 的值是 street；WorldDetailPage 调用 useParams 拿到 { id: 'street' }，用 getWorld 从 worlds.ts 里找到街头的数据，渲染出街头详情页。NavBar 在 Routes 外面，所以一直显示。
loading="lazy"。lazy 和 Suspense 让测试页按需加载，并在加载时显示“加载中”。/code-review 审查自己的组件，并对每条意见说出接受或不接受的理由。到昨天为止，新官网的功能已经齐了：四个页面、三个世界的详情页、导航、测试、留言。但“功能齐了”和“粉丝用起来舒服”之间，还差一段距离。换成粉丝的视角想一想：
这些都不是 bug，功能都“能用”，但每一处都在消耗访客的耐心。打磨，就是站在真实访客的角度，把这些小别扭一个个找出来修掉。今天上午讲四类最常见的打磨：图片、加载状态、404 页面、滚动位置，最后学用 /code-review 请 Claude 帮你找你自己没发现的问题。
手机拍的照片通常有 4000 像素宽，一张 3 到 5 MB。而你的穿搭卡片在手机上显示时只有三四百像素宽。把一张 4000 像素的照片塞进 400 像素的格子里，就像用一辆大卡车送一封信：送到了，但又慢又费油。
图片优化主要做三件事：
sips，一行命令就能批量缩小。loading="lazy"，浏览器就会自动这样做。图片放在哪？Vite 项目里有两个选择：放在 src/assets/ 里用 import 引入，或者放在 public/ 文件夹里直接用路径引用。public 里的文件会原样复制到网站根目录：public/looks/street-1.jpg 在网页里的地址就是 /looks/street-1.jpg。穿搭照片数量多、会经常增减，而且地址要写进数据文件里，放 public 最简单。你的头像 /avatar.jpg 就是这样放的。
street-1.jpg。Mac 的文件系统默认不区分大小写，Street-1.JPG 和 street-1.jpg 在你电脑上是同一个文件；但 Vercel 的服务器区分大小写，大小写不一致的话，本地好好的图片上线后就是 404。dongge-react/src/components/LookCard.tsx（片段）
{look.imageUrl && (
<img
src={look.imageUrl}
alt={`${getWorldName(look.world)}风格穿搭：${look.title}`}
width={600}
height={800}
loading="lazy"
decoding="async"
className="aspect-[3/4] w-full bg-ink/10 object-cover"
/>
)}逐行解释：
{look.imageUrl && (...)}：DAY 28 学的条件渲染。不是每套穿搭都有照片，有才显示。alt：图片的文字说明。读屏软件会把它读给视障用户听，图片加载失败时也会显示这段文字。DAY 04 学过，这里用模板字符串拼出“街头风格穿搭：Baggy 裤配 Vans”这样具体的描述，而不是笼统的“图片”。width 和 height：告诉浏览器图片的宽高比例。浏览器在图片下载完之前就能按比例留好位置，下面的文字不会在图片出现时突然被往下推。这种“页面内容跳来跳去”的现象叫布局偏移，特别容易让人点错按钮。loading="lazy"：懒加载，快滑到它附近时才开始下载。decoding="async"：让浏览器在后台解码图片，不卡住页面的其他部分。aspect-[3/4]：Tailwind 的任意值写法，把图片区域固定成 3:4 的竖图比例，不管原图是什么比例，卡片都一样高，列表整齐。object-cover：图片按比例缩放填满这个区域，多出来的部分裁掉，不会被压扁或拉长。bg-ink/10：图片还没加载出来时，先显示一块浅色的底，访客知道“这里有东西正在来”，而不是一片空白。这就是一个最简单的图片加载状态。你的整个网站现在被打包成了一个 JavaScript 文件。访客打开首页时，连测试小游戏的代码也一起下载了，哪怕她根本不打算做测试。网站越大，这个文件越大，首页就越慢。
解决办法叫代码分割：把某些页面的代码拆成单独的文件，等访客真的要去那个页面时再下载。React 提供了 lazy 来做这件事：
dongge-react/src/App.tsx（片段）
import { lazy, Suspense } from 'react'
const QuizPage = lazy(() => import('./pages/QuizPage'))
<Suspense fallback={<Loading />}>
<Routes>
{/* ... */}
<Route path="/quiz" element={<QuizPage />} />
</Routes>
</Suspense>逐行解释：
import('./pages/QuizPage')：注意这里的 import 带括号，是一个函数调用，叫动态导入。它返回一个 Promise（DAY 22 学过），意思是“需要的时候再去下载这个文件”。打包工具看到它，就会把 QuizPage 及它用到的测试组件拆成一个单独的 JS 文件。lazy(() => ...)：把动态导入包装成一个组件。第一次渲染 <QuizPage /> 时，React 才会执行这个函数去下载代码。要求 QuizPage 文件是用 export default 导出的，你的页面组件都是。const QuizPage = lazy(...) 要写在组件函数外面、文件的顶层。写在组件里面的话，每次渲染都会生成一个“新的” QuizPage，测试进度会不断被重置。<Suspense fallback={...}>：代码还在下载时，React 不知道该显示什么，Suspense 就是告诉它“等待期间先显示 fallback 里的东西”。这里显示一个 Loading 组件。下载完一次之后，浏览器已经有了这段代码，再进测试页就不会再看到加载中了。在你电脑上网速很快，可能根本看不到加载中；下午会用开发者工具模拟慢速网络来观察它。
要不要把每个页面都改成 lazy？不必。首页是大部分访客的第一站，应该立刻显示；三个世界、链接页很小。测试页代码相对多，而且只有一部分访客会去，最适合按需加载。先拆最大、最少人用的那部分，这是做性能优化的基本思路，DAY 65 你会系统地学。
昨天你看到了：输入一个不存在的网址，页面只剩导航，下面一片空白。对访客来说，这等于“网站坏了”。一个好的 404 页面要做到三件事：说清楚发生了什么（页面不存在），语气友好不责怪人（可能是网址打错了），给出回去的路（回首页、去链接页）。
在 React Router 里，用一个特殊的路径 * 表示“其他所有网址”：
<Route path="*" element={<NotFoundPage />} />还记得昨天说的“越具体的路径分越高”吗？* 能匹配任何网址，但它是最不具体的，所以只有在其他路由都匹配不上时才会轮到它，正好当“兜底”。
还有一种“找不到”：/world/abc。它能匹配 /world/:id 这一行，路由层面是“找到了”，但数据里没有 abc 这个世界。昨天你在 WorldDetailPage 里写了一段简单的提示，今天把它换成同一个 NotFoundPage 组件，两种情况的体验就一致了。
传统网站每次换页都是重新加载，自然从顶部开始。单页应用换页只是换了组件，浏览器的滚动位置不会变。于是出现一个怪现象：在三个世界页拉到底，点进详情页，新页面也停在底部。
解决办法是用 DAY 30 学的 useEffect：“当网址变了，就滚回顶部”。React Router 的 useLocation 能拿到当前网址的信息：
dongge-react/src/components/ScrollToTop.tsx
import { useEffect } from 'react'
import { useLocation } from 'react-router'
export default function ScrollToTop() {
const { pathname } = useLocation()
useEffect(() => {
window.scrollTo(0, 0)
}, [pathname])
return null
}逐行解释：useLocation() 返回当前位置的信息，pathname 是路径部分，比如 /world/street。依赖数组写 [pathname]，所以每次换页，effect 都会执行一次 window.scrollTo(0, 0)，滚到页面最左上角。组件 return null，它不显示任何东西，只负责做这件事。把它放在 App 里 BrowserRouter 的范围内就能工作。这是一个很好的例子，说明组件不一定要显示东西，也可以只负责一个副作用。
到今天，你的项目已经有二十多个文件。自己写的代码自己看，很难发现问题，因为你知道自己“想写的是什么”，眼睛会自动跳过写错的地方。这时候需要一个“第二双眼睛”。
Claude Code 自带一个审查命令 /code-review。在 Claude Code 的输入框里输入它并回车，Claude 会读你还没提交的改动，列出可能的 bug 和可以改进的地方。你也可以在后面加一个路径，比如 /code-review src/components，让它审查整个文件夹。
拿到审查结果后，按这三步处理：
把每条意见和你的决定、理由记在一张表里，今晚验收要用。能说出“为什么不接受”，说明你是真的理解了自己的代码，而不是只会照着建议改。
挑照片，放进 public
先看看旧官网里有哪些穿搭照片：
ls -lh ~/Desktop/dongge-site/looks给每个世界挑一到两张，复制到新项目里，并改成小写的新名字（下面的原文件名换成你实际的文件名）：
cd ~/code/dongge-react
mkdir -p public/looks
cp ~/Desktop/dongge-site/looks/你的照片1.jpg public/looks/gentleman-1.jpg
cp ~/Desktop/dongge-site/looks/你的照片2.jpg public/looks/street-1.jpg
cp ~/Desktop/dongge-site/looks/你的照片3.jpg public/looks/thai-1.jpg
ls -lh public/looks如果旧文件夹里的照片不够，也可以用手机里的新照片。iPhone 的 HEIC 格式浏览器不一定能显示，要先转成 JPEG（见下一步）。
压缩照片
用 Mac 自带的 sips 把照片的长边缩到 1200 像素（它会直接修改 public/looks 里的文件，桌面上的原图不受影响）：
sips -Z 1200 public/looks/*.jpg
ls -lh public/looks如果某张是 HEIC，先转换：sips -s format jpeg 原图.heic --out public/looks/thai-1.jpg，再执行上面的缩小命令。
想再小一点，可以打开 squoosh.app，把图片拖进去，右侧格式选 WebP，质量拉到 75 左右，下载后放回 public/looks（扩展名变成 .webp，数据里的路径也要跟着改）。
ls -lh 显示每张图在 300 KB 以内，最好在 200 KB 左右。数据里加上图片地址
在 src/types.ts 的 Look 类型里加一个可选字段（DAY 26 学过，问号表示可以没有）：
export type Look = {
id: number
title: string
world: World
description: string
imageUrl?: string
}然后在 src/data/looks.ts 里，给有照片的那几项加上 imageUrl，比如：
{ id: 1, title: '深灰马甲配白衬衫', world: 'gentleman', description: '打斯诺克那天穿的，袖子挽到小臂。', imageUrl: '/looks/gentleman-1.jpg' },没有照片的项保持原样，不用写 imageUrl。标题和描述最好改成和照片里真实的穿搭一致。
卡片显示照片
dongge-react/src/components/LookCard.tsx
import type { Look } from '../types'
import { getWorldName } from '../data/worlds'
type LookCardProps = {
look: Look
}
export default function LookCard({ look }: LookCardProps) {
return (
<article className="overflow-hidden rounded-2xl bg-card shadow-sm">
{look.imageUrl && (
<img
src={look.imageUrl}
alt={`${getWorldName(look.world)}风格穿搭：${look.title}`}
width={600}
height={800}
loading="lazy"
decoding="async"
className="aspect-[3/4] w-full bg-ink/10 object-cover"
/>
)}
<div className="p-5">
<p className="text-sm text-accent">{getWorldName(look.world)}</p>
<h3 className="mt-1 text-lg font-bold">{look.title}</h3>
<p className="mt-2 text-sm opacity-80">{look.description}</p>
</div>
</article>
)
}和之前相比：外层去掉了 p-5、加了 overflow-hidden（让图片的直角被卡片的圆角裁掉），文字部分包进一个带 p-5 的 div，图片就能贴满卡片顶部。
观察懒加载
打开开发者工具的 Network（网络）面板，点上方的 Img 过滤，勾选 Disable cache（停用缓存）。把浏览器窗口拉矮一点，刷新三个世界页，先不要滚动，看加载了哪几张图；再慢慢往下滑，观察新的图片请求是不是随着滚动才出现。
测试页按需加载
新建加载组件：
dongge-react/src/components/Loading.tsx
export default function Loading() {
return (
<p role="status" className="py-16 text-center opacity-70">
加载中……
</p>
)
}role="status" 让读屏软件知道这是一条状态提示。App.tsx 的完整改法在第 8 步一起给出。
做 404 页面
dongge-react/src/pages/NotFoundPage.tsx
import { Link } from 'react-router'
export default function NotFoundPage() {
return (
<div className="py-20 text-center">
<p className="text-6xl font-bold text-accent">404</p>
<h1 className="mt-4 text-2xl font-bold">这个页面不存在</h1>
<p className="mt-2 opacity-80">可能是网址打错了，也可能这个页面已经搬走了。</p>
<div className="mt-8 flex flex-col gap-3 sm:flex-row sm:justify-center">
<Link
to="/"
className="rounded-full bg-accent px-6 py-3 font-medium text-white transition hover:opacity-90"
>
回到首页
</Link>
<Link to="/links" className="rounded-full border border-accent px-6 py-3 font-medium text-accent">
去链接页找我
</Link>
</div>
</div>
)
}再打开 WorldDetailPage.tsx，顶部加上 import NotFoundPage from './NotFoundPage'，把 if (!world) 里原来那段 return 换成：
if (!world) {
return <NotFoundPage />
}文件里其他地方还在用 Link（“测一测”按钮），所以 Link 的 import 要保留。
新建 ScrollToTop，更新 App.tsx
新建 src/components/ScrollToTop.tsx，内容是上午第 6 节的完整代码。然后把 App.tsx 改成：
dongge-react/src/App.tsx
import { lazy, Suspense, useEffect, useState } from 'react'
import { Route, Routes } from 'react-router'
import type { World } from './types'
import NavBar from './components/NavBar'
import Loading from './components/Loading'
import ScrollToTop from './components/ScrollToTop'
import HomePage from './pages/HomePage'
import WorldsPage from './pages/WorldsPage'
import WorldDetailPage from './pages/WorldDetailPage'
import LinksPage from './pages/LinksPage'
import NotFoundPage from './pages/NotFoundPage'
import { getWorldName } from './data/worlds'
const QuizPage = lazy(() => import('./pages/QuizPage'))
const THEME_KEY = 'dongge-theme'
function getSavedTheme(): World {
const saved = localStorage.getItem(THEME_KEY)
if (saved === 'gentleman' || saved === 'street' || saved === 'thai') {
return saved
}
return 'gentleman'
}
export default function App() {
const [theme, setTheme] = useState<World>(getSavedTheme)
useEffect(() => {
localStorage.setItem(THEME_KEY, theme)
}, [theme])
useEffect(() => {
document.title = `三岁的东哥 · ${getWorldName(theme)}`
}, [theme])
return (
<div className={`theme-${theme} min-h-screen bg-page text-ink transition-colors`}>
<ScrollToTop />
<div className="mx-auto max-w-4xl px-4">
<NavBar />
<main className="pb-16">
<Suspense fallback={<Loading />}>
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/worlds" element={<WorldsPage />} />
<Route path="/world/:id" element={<WorldDetailPage />} />
<Route path="/links" element={<LinksPage theme={theme} onThemeChange={setTheme} />} />
<Route path="/quiz" element={<QuizPage />} />
<Route path="*" element={<NotFoundPage />} />
</Routes>
</Suspense>
</main>
</div>
</div>
)
}变化有四处：QuizPage 的普通 import 换成了 lazy；Routes 外面包了 Suspense；最后加了 path="*" 的兜底路由；最外层 div 里放了 ScrollToTop。
/abc 和 /world/abc 都显示 404 页面，两个按钮都能用；在三个世界页拉到底部点进一个世界，新页面从顶部开始。亲眼看到“加载中”和拆出来的文件
在 Network 面板里，把 No throttling（不限速）改成 Slow 4G 或 3G，勾上 Disable cache，刷新首页，再点导航的“测一测”，你会先看到“加载中……”，然后测试页出现，Network 里多了一个新的 JS 请求。看完把限速改回 No throttling。
再运行一次构建：
npm run build运行 /code-review，整理审查意见
先不要提交今天的改动。在 ~/code/dongge-react 打开 Claude Code，输入 /code-review 回车，它会审查你今天还没提交的所有改动。再运行一次 /code-review src/components，审查整个组件文件夹。
把所有意见整理成一张表，每条写上：问题是什么、你接受还是不接受、理由。接受的，自己动手改；看不懂的，追问 Claude 直到弄懂为止。
在真实手机上逐页检查
让开发服务器允许局域网访问：
npm run dev -- --host终端会显示一行 Network: http://192.168.x.x:5173/。手机连上和电脑相同的 Wi-Fi，用浏览器打开这个地址。如果 Mac 弹窗询问是否允许接受传入的网络连接，选择允许。然后按下面的清单逐页检查：
提交
npm run build
git add .
git commit -m "DAY 35 图片、加载状态、404 和审查修改"明天就是上线日：把新官网部署到 Vercel，替换掉旧的静态官网。
public/looks/street-1.jpg 要写成 /looks/street-1.jpg。再检查大小写和扩展名是否和文件完全一致（.jpg 和 .jpeg、.JPG 都算不同）。sips -s format jpeg 转成 JPEG，或在手机上导出为 JPEG。export default。检查 QuizPage.tsx 是不是 export default function QuizPage。const QuizPage = lazy(...) 写到了 App 组件函数里面。它必须写在文件顶层、组件外面。/code-review src，就会审查指定的文件夹。说出审查意见里你接受的 2 条和不接受的 1 条，以及理由。
每个人的审查结果不同，答案按你自己的表格来说，但要做到“有具体的问题、有明确的决定、有站得住的理由”。示例：接受第 1 条，“LookCard 的图片缺少 width 和 height”，理由是不写的话图片加载时下面的文字会跳动，影响点击；接受第 2 条，“WorldDetailPage 找不到世界时的提示和 404 页面不一致”，理由是两种迷路情况应该给同样的出路，所以改成复用 NotFoundPage；不接受第 3 条，“给 WorldCard 增加 color、size 等可选 props 以便扩展”，理由是目前只有一种用法，颜色已经通过 theme class 解决，提前加 props 会让组件更难读，等真的需要第二种样式时再改。
img 标签的 width、height 和 loading="lazy" 分别解决什么问题？
width 和 height 让浏览器在图片下载完之前就知道它的宽高比例，提前留好位置，避免图片出现时把下面的内容往下推（布局偏移），访客不容易点错。loading="lazy" 让图片等到快滚动到它附近时才下载，页面刚打开时只下载看得见的几张，打开更快，也省访客的流量。
访问 /abc 和 /world/abc 都会看到 404 页面，分别是哪段代码让它显示出来的？
/abc 不匹配任何具体的路由，只能匹配最后的兜底路由 <Route path="*" element={<NotFoundPage />} />，所以由路由直接显示 NotFoundPage。/world/abc 能匹配 /world/:id，先渲染了 WorldDetailPage；组件里 getWorld('abc') 返回 undefined，走进 if (!world) return <NotFoundPage />，由页面组件自己显示 404。前者是“网址不存在”，后者是“网址格式对但数据不存在”。
npm run build 做了什么、dist 文件夹里有什么，并用 npm run preview 在本地预览正式版本。vercel.json 的 rewrites 解决它。这是阶段 3 的最后一天，也是上线日。DAY 03 你第一次把旧官网放上了网，DAY 12 上线了链接主页，DAY 24 上线了测试小游戏。今天上线的是你用 TypeScript、React、Tailwind、React Router 从零搭起来的新官网，它会替换掉 DAY 03 那个旧的静态版本。
飞行员每次起飞前，不管飞过多少次，都要对着检查单一项项确认。原因很简单：人会忘事，而上线后出的问题，第一个发现的往往是粉丝。上线前花半小时对着清单检查，比上线后被人截图说“你网站打不开”要好得多。
你的上线检查清单：
npm run build 没有任何报错。npm run preview 打开，每一页都走一遍。example.com。这几天你一直在用 npm run dev，它启动的是开发服务器：你改一行代码，浏览器立刻更新，报错信息也很详细，方便开发。但它不适合给访客用：文件没有压缩，代码是一个个零散的模块，速度也不是最快的。
上线要用的是正式版本，由 npm run build 生成。打开 package.json，你会看到它实际执行的是：
"build": "tsc -b && vite build"两个命令用 && 连起来，意思是“前一个成功了，才执行后一个”：
tsc -b：TypeScript 对整个项目做一次完整的类型检查。开发时编辑器只检查你打开的文件，这里会检查所有文件。任何类型错误、没用到的变量，都会让构建在这一步停下来。这就是 DAY 25 说的好处：错误在上线前被拦下，而不是在粉丝的手机上爆发。vite build：把你所有的 tsx、ts、css 打包、压缩，输出到 dist 文件夹。构建完，dist 里大致是这样：
dist/
├── index.html 唯一的 HTML 文件
├── avatar.jpg 从 public 原样复制过来
├── looks/ 从 public 原样复制过来
└── assets/
├── index-Bx7k2QpA.js 主程序（名字里的一串字符每次构建可能不同）
├── QuizPage-D3fL9sWe.js 昨天按需加载拆出来的测试页
└── index-C8mPq1Zt.css Tailwind 生成的样式，只包含你用到的类文件名里那串乱码叫哈希值，是根据文件内容算出来的，内容一变它就变。这样浏览器可以放心地把这些文件缓存很久：你更新了代码，文件名变了，浏览器自然会下载新的；没变的文件继续用缓存，访客打开更快。
这个 dist 文件夹就是你要交给服务器的全部东西：一个 HTML、几个 JS 和 CSS、一些图片。没有 Node.js，没有 React 源代码，只是一堆静态文件。
构建完成后，运行 npm run preview，Vite 会用 dist 里的文件在 http://localhost:4173 启动一个本地服务器。你看到的就是访客将来看到的版本：压缩过的代码、拆分过的文件、生产环境的行为。
为什么不直接用 dev 检查就好？因为有些问题只在正式版里出现。比如昨天说的 StrictMode 双重执行，只在开发环境发生；某些写法在开发时能跑，打包后路径变了就找不到文件。上线前用 preview 过一遍，相当于“彩排”。
不过要注意，preview 和 dev 一样，对任何网址都会返回 index.html，所以在 preview 里刷新 /world/street 是正常的。这一点和 Vercel 不同，第 5 节会讲到，它正是今天最大的一个坑。
你已经用 Vercel 部署过三次，今天再把流程在脑子里过一遍，因为 React 项目比纯 HTML 多了一步“构建”：
npm install 安装依赖，再运行 npm run build。dist 文件夹里的静态文件发布到全球的服务器节点上，给你一个网址。Vercel 能自动识别 Vite 项目，构建命令和输出目录（dist）一般不用改。注意第二步：Vercel 是在一台干净的 Linux 服务器上从零安装、从零构建的。你电脑上没提交的文件，它拿不到；你电脑上能忽略的大小写差异，它不会忽略。所以“本地构建通过”是上线的前提，但不是保证。
这是单页应用部署时最经典的问题，下午你会亲眼遇到：网站部署成功，从首页点来点去一切正常；但在 /world/street 页面按一下刷新，或者把这个网址直接发给朋友打开，看到的却是 Vercel 的 404: NOT_FOUND 页面。
要理解它，得分清两种“到达一个页面”的方式：
/world/street。/world/street 这个页面。”第二种情况下，Vercel 会去你发布的静态文件里找：有没有一个叫 world/street 的文件，或者 world/street/index.html？回头看第 2 节的 dist 结构，根本没有。你的整个网站只有一个 index.html，所有页面都是它加载的 JavaScript 画出来的。Vercel 找不到文件，就只能回答 404。
打个比方：你的网站是一个只有一个前台的大厅（index.html），前台后面的大屏幕能显示任何房间（React Router）。熟客从大厅里用遥控器切换房间，一点问题没有；但新客人拿着“302 房间”的地址直接找过来，楼管（Vercel）一看，这栋楼里没有 302 这个门牌，就说“查无此房”。其实只要让客人先到前台，前台一看地址，就能在大屏幕上把 302 房间显示给他看。
你可以在开发者工具的 Network 面板里亲眼看到这个区别：在网站里点 Link 换页时，列表里不会出现新的页面请求（最多出现测试页那个按需加载的 JS）；按刷新时，列表第一行就是对 /world/street 这个网址的请求，状态码一栏写着 404。
那为什么本地开发时从来没遇到？因为 Vite 的开发服务器和 preview 服务器都内置了一个“兜底”：不管请求什么网址，找不到文件就返回 index.html。Vercel 部署静态网站时默认没有这个兜底，需要你明确告诉它。
告诉 Vercel“找不到文件时，把 index.html 给他”，只需要在项目根目录加一个 vercel.json 文件：
dongge-react/vercel.json
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}逐行解释：
"$schema"：告诉编辑器这个文件的格式规范，VS Code 会据此给你自动补全和错误提示。不写也能工作，写上更安全。"rewrites"：重写规则的列表，这里只有一条。"source": "/(.*)"：匹配哪些请求。(.*) 是一个正则表达式，意思是“任意字符，任意长度”，所以 /world/street、/quiz、/abc 全都匹配。"destination": "/index.html"：匹配到的请求，都用 index.html 来回答。加上这条规则后，刷新 /world/street 的完整过程变成：浏览器请求 /world/street；Vercel 找不到这个文件，按规则返回 index.html，地址栏里的网址保持不变；浏览器加载 JavaScript，React 启动；BrowserRouter 读到地址栏里是 /world/street，Routes 匹配到 WorldDetailPage，街头详情页出现。
你可能会担心：规则说“所有请求都返回 index.html”，那 JS、CSS、图片的请求会不会也被换成 index.html？不会。Vercel 的处理顺序是先找真实存在的文件，找不到才使用 rewrites。/assets/index-Bx7k2QpA.js、/looks/street-1.jpg 都是真实文件，照常返回；只有像 /world/street 这样没有对应文件的网址，才会交给 index.html。
对于完全不存在的网址，比如 /abc，Vercel 也会返回 index.html，然后由你昨天写的 path="*" 路由显示你自己的 404 页面。这就是昨天提示里说的：单页应用的 404 是 JavaScript 画出来的。
rewrite 和 redirect 的区别，今天一定要分清：
| rewrite（重写） | redirect（重定向） | |
|---|---|---|
| 地址栏 | 不变 | 变成新网址 |
| 发生了什么 | 服务器悄悄用另一个文件回答这个请求 | 服务器告诉浏览器“去另一个地址”，浏览器再发一次请求 |
| 今天的例子 | 任何网址都用 index.html 回答，React Router 负责显示对应页面 | 旧官网的网址自动跳到新官网 |
DAY 03 你把桌面上的 dongge-site 部署成了 Vercel 上的一个项目，那个网址可能已经放进了某些平台的简介里，或者被人收藏了。新官网上线后，不能让这些人还停在旧页面。办法是让旧网址自动跳到新网址，也就是 redirect。
在旧官网的仓库里也加一个 vercel.json：
~/Desktop/dongge-site/vercel.json
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"redirects": [
{ "source": "/(.*)", "destination": "https://dongge-react.vercel.app/", "permanent": false }
]
}"source": "/(.*)"：旧网站的任何网址。"destination"：跳到新官网的首页。把这里换成你新官网实际的网址。"permanent": false：临时重定向（状态码 307）。如果写 true 就是永久重定向（308），浏览器会把“旧网址等于新网址”记很久，以后你想改都很难清掉。DAY 69 你还要绑定自己的域名，网址还会再变，现在用临时的更稳妥。旧仓库里的 index.html、looks 图片都不用删，它们还在 Git 历史里，只是访客不会再看到。deploy.sh 和 nginx-dongge.conf 是更早以前用自己的服务器部署时留下的，和 Vercel 无关，也可以先留着。
DAY 12 上线的 links 项目也是同样的道理。如果你各平台简介里放的是 links 的网址，可以暂时不动它，等新官网稳定运行几天后，再用同样的 redirects 写法把它跳到新官网的 /links 页，destination 写成 https://你的新官网网址/links。旧项目先不要在 Vercel 上删除，保留着它，想撤回时删掉 vercel.json 再推送一次就恢复了。给自己留一条退路，是上线时的好习惯。
最后一步是手动的：去小红书、TikTok、Facebook、Instagram 的主页简介里，把链接换成新官网的网址（或者直接放 /links 页的网址）。这一步由你自己决定什么时候做、放哪个页面。
清理占位内容，写好页面信息
先找出所有还没替换的占位链接：
cd ~/code/dongge-react
grep -rn "example.com" src把 src/data/platforms.ts 里的四个链接换成你真实的主页地址，直到上面的命令没有输出。然后打开项目根目录的 index.html，把语言、标题改好，加一行描述。改完大致是这样（icon 那一行保留你文件里原来的写法）：
dongge-react/index.html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="三岁的东哥：在外面是绅士、拳手、潮男，在你面前三岁。" />
<title>三岁的东哥</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>lang="zh-CN" 告诉浏览器和读屏软件这是中文网页；title 和 description 会出现在浏览器标签、搜索结果和一些聊天软件的链接预览里。虽然 App 里的 useEffect 会在运行时改标题，但在 JavaScript 运行之前，别人看到的是这里写的内容。
构建
npm run build如果有报错，逐条读错误信息：它会告诉你哪个文件、哪一行、什么问题。常见的是没用到的 import 和类型不匹配。修完再构建，直到成功。
ls dist dist/assets 看看里面的文件，对照上午第 2 节的结构。本地预览正式版，对着清单检查
npm run preview打开 http://localhost:4173，按上午第 1 节的清单逐项检查：每个导航、每个按钮、每张世界卡片、测试结果页的两个按钮、404 页的两个按钮；四个平台按钮在新标签页打开的是你真实的主页；开发者工具的控制台没有红色报错。检查完按 Ctrl + C 停掉。
确认 Git 状态并提交
cat .gitignore
git status确认 .gitignore 里有 node_modules 和 dist：依赖由 Vercel 自己安装，dist 由 Vercel 自己构建，都不需要提交。git status 里不应该出现这两个文件夹。然后提交：
git add .
git commit -m "DAY 36 上线准备：页面信息和真实链接"推到 GitHub
在浏览器打开 github.com，右上角 + 号选 New repository，仓库名填 dongge-react，公开或私有都可以，不要勾选添加 README、.gitignore 或 license（你本地已经有了），点 Create repository。然后在终端运行（把“你的用户名”换成你的 GitHub 用户名）：
git remote add origin https://github.com/你的用户名/dongge-react.git
git branch -M main
git push -u origin main如果你 DAY 02 装好了 GitHub CLI 并已登录，也可以用一行命令代替上面的网页操作和前两行：gh repo create dongge-react --public --source=. --push。
导入 Vercel 并部署
打开 vercel.com 并登录，点 Add New，选 Project，在列表里找到 dongge-react 点 Import。确认 Framework Preset 自动识别为 Vite，构建命令和输出目录保持默认（npm run build 和 dist），项目名称填 dongge-react，点 Deploy。按钮文字如果和这里略有不同，以页面上的实际文字为准。
https://dongge-react.vercel.app（名字被占用时会带一个后缀，以你实际看到的为准）。点开它，看到新官网的首页。亲眼看到刷新 404
在线上网址里，从首页点“三个世界”，再点进街头，一切正常。现在在 /world/street 页面按 Cmd + R 刷新。
加上 vercel.json，推送
在项目根目录（和 package.json 同一层，不是 src 或 public 里）新建 vercel.json，内容是上午第 6 节的代码。然后：
git add vercel.json
git commit -m "加上 SPA rewrites，修复刷新子页面 404"
git push打开 Vercel 项目页面，能看到一次新的部署正在进行，这是 push 自动触发的。
线上再验证一遍
部署完成后，逐项检查：在 /world/street 刷新；在新的无痕窗口里直接打开 你的网址/quiz 和 你的网址/links；打开 你的网址/abc，应该看到你自己做的 404 页面；三个世界页的照片都能显示（线上不显示的话，多半是文件名大小写问题，见“常见问题”）。
在手机上检查线上版本
用手机打开线上网址，把昨天的手机检查清单再过一遍。再把某个子页面（比如 /quiz）的链接发给一位朋友，请她在自己的手机上打开并做一次测试，记下她卡住或觉得别扭的地方。
让旧官网跳转到新官网
进入旧官网的文件夹，确认它和 GitHub 是连着的：
cd ~/Desktop/dongge-site
git status
git remote -v新建 vercel.json，内容是上午第 7 节的代码，把 destination 换成你新官网的实际网址。如果这个文件夹里已经有 vercel.json，就把 redirects 这一项加进去，而不是整个覆盖。然后提交并推送：
git add vercel.json
git commit -m "旧官网跳转到新官网"
git push收尾：更新简介，做一次验收练习
决定要不要现在就把各平台简介里的链接换成新官网（首页或 /links），这一步你自己在各个 App 里操作。
然后给自己计时 45 分钟，做今晚验收第 1 题：不看课件和以前的代码，在 ~/code/learn 里新建一个 React 项目，做出一个“按世界筛选穿搭”的列表：
cd ~/code/learn
npm create vite@latest react-filter -- --template react-ts
cd react-filter
npm install
npm run dev卡住的地方记下来，做完后再翻课件对照。它们就是你接下来最需要复习的知识点。
npm run build 就能复现）；import 的大小写和文件名不一致，比如写了 './components/navbar' 而文件叫 NavBar.tsx，Mac 上能找到，Linux 上找不到。vercel.json、有没有 push 上去、新的部署是否已经完成。不看教程，从零建一个 React 项目，做出一个带筛选的列表。
用 npm create vite@latest react-filter -- --template react-ts 创建项目，npm install 后 npm run dev。核心是：数据是一个带类型的数组；只用一个 state 记住当前的筛选条件；筛选结果在渲染时计算，不存成 state；用 map 渲染按钮和列表，每一项有稳定的 key；没有结果时显示空状态。参考写法：
import { useState } from 'react'
type World = 'gentleman' | 'street' | 'thai'
type Filter = World | 'all'
type Look = { id: number; title: string; world: World }
const looks: Look[] = [
{ id: 1, title: '深灰马甲配白衬衫', world: 'gentleman' },
{ id: 2, title: 'Baggy 裤配 Vans', world: 'street' },
{ id: 3, title: '红色泰拳短裤', world: 'thai' },
]
const filters: { value: Filter; label: string }[] = [
{ value: 'all', label: '全部' },
{ value: 'gentleman', label: '绅士' },
{ value: 'street', label: '街头' },
{ value: 'thai', label: '泰风' },
]
export default function App() {
const [filter, setFilter] = useState<Filter>('all')
const visibleLooks = filter === 'all' ? looks : looks.filter((look) => look.world === filter)
return (
<main>
<div>
{filters.map((item) => (
<button key={item.value} type="button" onClick={() => setFilter(item.value)}>
{filter === item.value ? `[${item.label}]` : item.label}
</button>
))}
</div>
{visibleLooks.length === 0 ? (
<p>没有符合条件的穿搭</p>
) : (
<ul>
{visibleLooks.map((look) => (
<li key={look.id}>{look.title}</li>
))}
</ul>
)}
</main>
)
}为什么在 Vercel 上刷新 /world/street 会 404？vercel.json 的 rewrites 是怎么解决的？
单页应用只有一个 index.html，所有页面都是 JavaScript 根据网址画出来的。在网站内点 Link 时，React Router 只是改了地址栏，没有向服务器发请求，所以正常。刷新或直接打开网址时，浏览器会向服务器请求 /world/street，Vercel 在发布的静态文件里找不到这个文件，就返回 404。rewrites 规则让所有找不到对应文件的请求都用 index.html 回答，地址栏不变；浏览器加载 JavaScript 后，React Router 读到网址是 /world/street，就显示街头详情页。真实存在的 JS、CSS、图片文件会被优先返回，不受这条规则影响。本地没遇到是因为 Vite 的开发和预览服务器自带这个兜底。
今天你用了 rewrite 和 redirect 各一次。它们有什么区别？为什么旧官网的跳转要用 "permanent": false？
rewrite 是服务器悄悄用另一个文件回答请求，地址栏不变，今天用来让任何网址都返回 index.html；redirect 是服务器告诉浏览器去另一个地址，浏览器再请求一次，地址栏会变成新网址，今天用来把旧官网跳到新官网。用 "permanent": false 是临时重定向（307），浏览器不会把这个跳转永久记住；如果写成永久重定向（308），浏览器会长期缓存，DAY 69 绑定域名后新网址变了，已经缓存的访客很难被纠正过来。
~/code/nextjs-dashboard，能说出 app、app/ui、app/lib、public 各放什么。clsx 四种写样式的方式各适合什么场景。next/font 加字体、用 next/image 加图片，并讲出它们比直接写 <link> 和 <img> 好在哪里。page.tsx 做出 /dashboard、/dashboard/customers、/dashboard/invoices 三个网址，并用 layout.tsx 给它们加一个共享侧边栏。昨天你把 dongge-react 部署上线了。回头想想这个项目是怎么搭起来的：Vite 负责打包，React 负责画界面，React Router 负责多页面，数据写在 TypeScript 文件里。每一块都是你自己挑、自己接起来的。
打个比方：React 像一台好发动机。发动机很重要，但光有发动机，车还跑不起来，你还得自己配底盘、方向盘、刹车。Next.js 是一辆已经装好的整车，发动机还是 React，但路由、打包、图片优化、部署方式都按一套约定配好了。你按约定把文件放对位置，功能就有了。
Next.js 最大的不同，是它让一部分代码在服务器上运行。你之前写的 React 代码全部在访客的浏览器里跑：浏览器先下载一大包 JavaScript，再把页面画出来。Next.js 可以先在服务器上把页面画好，直接把 HTML 发给浏览器，所以打开更快；更重要的是，服务器上的代码可以直接连数据库、使用密钥，而这些东西绝不能出现在浏览器里。这就是接下来 18 天“全栈”的基础：DAY 40 起你要连数据库，DAY 43 起要把粉丝的提问存进数据库。
今天还有一个变化：Claude 的角色升级为结对搭档。你可以让它在 Plan 模式（只出方案、不改文件的模式）里先把思路讲清楚，也可以让它写重复性的样板代码。但有两条规矩：核心逻辑你自己写；Claude 改过的每一行，你都要读懂再接受。读不懂就追问，直到能用自己的话讲出来。
Next.js 官网有一门免费的 App Router 课程，做的是一个叫 Acme 的财务后台：公开的首页、登录页、只有登录后才能进的后台，后台里可以新建、修改、删除发票，数据存在 PostgreSQL 数据库里。这个项目和你的官网很像：前台给访客看，后台给你自己管理内容。
课程是英文的。建议你代码部分看原文，说明文字看不懂时可以用浏览器翻译，再对照今天的课件。我们的安排是：
教程用的起步项目（starter）已经写好了很多界面组件，你不用从零开始画表格和卡片，只需要一步步把它们接起来。建好后，项目里最重要的几个位置是：
nextjs-dashboard/
├── app/ 所有页面和路由都在这里
│ ├── layout.tsx 根布局：包住所有页面的外壳
│ ├── page.tsx 首页，对应网址 /
│ ├── lib/ 工具函数、类型定义、示例数据
│ │ ├── definitions.ts
│ │ └── placeholder-data.ts
│ └── ui/ 现成的界面组件和样式
│ ├── global.css
│ └── dashboard/ ...
├── public/ 图片等静态文件，网址从 / 开始
├── next.config.ts Next.js 的配置
└── package.json这里有一个会让你困惑的地方先说清楚：这个起步项目用的是 Tailwind v3，所以 global.css 开头是三行 @tailwind。而你在 DAY 32 学的是 Tailwind v4，写法是一行 @import "tailwindcss";。两种写法出来的类名基本一样，明天建 dongge-web 时会用回 v4 写法。教程项目只用来学习，不要把它的配置抄进正式项目。
pnpm-lock.yaml），它记录了每个依赖的确切版本。用 pnpm 安装，你拿到的就是教程作者测试过的那一套版本；改用 npm 会重新挑版本，可能装不上。这个项目用 pnpm，dongge-web 还是用 npm。第一种是全局样式。app/ui/global.css 里的规则会作用到每个页面。它必须在根布局 app/layout.tsx 里导入一次，所有页面才会有样式：
nextjs-dashboard/app/layout.tsx
import '@/app/ui/global.css'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}第一行的 @/ 是“项目根目录”的简写，@/app/ui/global.css 就是根目录下的 app/ui/global.css，不管当前文件在第几层文件夹，都不用写一串 ../../。RootLayout 接收一个 children，也就是当前要显示的页面，把它放进 <body> 里。你在 DAY 28 用过 children，这里是一回事。
第二种是 Tailwind 类，直接写在 className 里，你已经很熟了。第三种是 CSS Modules：把样式写在以 .module.css 结尾的文件里，导入后用 styles.类名 使用。
nextjs-dashboard/app/ui/home.module.css
.shape {
height: 0;
width: 0;
border-bottom: 30px solid black;
border-left: 20px solid transparent;
border-right: 20px solid transparent;
}它的好处是类名不会撞车。你在两个文件里都写 .shape，Next.js 会自动把它们改成两个不同的名字。可以把它想成每个组件有自己的衣柜，衣服不会被别的组件拿错。项目大了、多人协作时很有用；你的官网主要用 Tailwind，知道有这个选择就行。
第四种是 clsx，一个用来按条件拼 class 的小工具。比如发票状态是“待付款”显示灰色，“已付款”显示绿色：
nextjs-dashboard/app/ui/invoices/status.tsx（片段）
import clsx from 'clsx'
<span
className={clsx('inline-flex items-center rounded-full px-2 py-1 text-sm', {
'bg-gray-100 text-gray-500': status === 'pending',
'bg-green-500 text-white': status === 'paid',
})}
>第一个参数是永远都要的基础样式；第二个参数是一个对象，键是 class，值是条件，条件为真时这组 class 才会被加上。换到你的项目里，就是“当前选中的世界按钮高亮”这种需求，比手写三元运算符拼字符串清楚得多。
DAY 09 你用 Google Fonts 的 <link> 引入过字体。那种写法每次打开页面，浏览器都要额外去 Google 的服务器下载字体；字体到之前先用系统字体显示，到了再换，文字会闪一下、挤一下。这种“页面内容突然移位”有个专门的名字，叫布局偏移（CLS），是衡量网页体验的指标之一。
next/font 的做法是：在构建时就把字体文件下载好，和你的网站放在一起，访客打开页面时不用再去找 Google。
nextjs-dashboard/app/ui/fonts.ts
import { Inter } from 'next/font/google'
export const inter = Inter({ subsets: ['latin'] })Inter 是字体名，Google Fonts 上名字里的空格在这里换成下划线，比如 Noto Sans 写成 Noto_Sans。subsets: ['latin'] 表示只下载拉丁字母这一部分，文件更小。导出的 inter 对象有一个 className，加到 <body> 上就生效：<body className={`${inter.className} antialiased`}>。反引号里是你在 DAY 13 学过的模板字符串，把字体类名和 antialiased（让字体边缘更平滑的 Tailwind 类）拼在一起。
图片同理。直接写 <img>，你得自己操心大小、格式、懒加载。next/image 的 Image 组件会自动按屏幕大小提供合适尺寸的图片、转成更小的现代格式、等图片快滚到眼前才加载：
nextjs-dashboard/app/page.tsx（片段）
import Image from 'next/image'
<Image
src="/hero-desktop.png"
width={1000}
height={760}
className="hidden md:block"
alt="后台页面在电脑上的截图"
/>src 以 / 开头，指的是 public 文件夹里的文件。width 和 height 必须写：Next.js 靠它们提前算出图片的宽高比例，先把位置占好，图片加载完也不会把下面的文字顶下去。className="hidden md:block" 是你在 DAY 32 学的响应式前缀：手机上隐藏，平板以上显示。再放一张 hero-mobile.png 配 md:hidden，就能做到手机和电脑各看各的图。
在 dongge-react 里，你要在代码里写一张“路由表”，告诉 React Router 哪个网址显示哪个组件。Next.js 不需要路由表，它看 app 文件夹的结构：
| 文件位置 | 对应网址 |
|---|---|
app/page.tsx | / |
app/dashboard/page.tsx | /dashboard |
app/dashboard/invoices/page.tsx | /dashboard/invoices |
app/ui/fonts.ts | 没有网址，因为文件夹里没有 page.tsx |
规则只有两条：文件夹决定网址的每一段，page.tsx 决定这一段能不能被访问。一个文件夹里有 page.tsx，这个网址才存在；没有的话，这个文件夹只是用来放东西的普通文件夹。这也是 app/ui、app/lib 不会变成网址的原因。像 page、layout 这种有特殊含义的文件名，叫“约定文件”，名字必须一字不差。
最简单的页面长这样：
nextjs-dashboard/app/dashboard/page.tsx
export default function Page() {
return <p>Dashboard Page</p>
}export default 表示这个文件默认导出这个组件，Next.js 就是靠默认导出找到要显示什么的。函数名叫 Page 还是别的都可以，但必须是默认导出。
后台的三个页面左边都要有同一个侧边栏。每个页面各写一遍当然可以，但改一处就要改三处。layout.tsx 解决的就是这个问题：它是一个外壳，同一个文件夹以及所有子文件夹里的页面，都会被它包在里面。
nextjs-dashboard/app/dashboard/layout.tsx
import SideNav from '@/app/ui/dashboard/sidenav'
export default function Layout({ children }: { children: React.ReactNode }) {
return (
<div className="flex h-screen flex-col md:flex-row md:overflow-hidden">
<div className="w-full flex-none md:w-64">
<SideNav />
</div>
<div className="grow p-6 md:overflow-y-auto md:p-12">{children}</div>
</div>
)
}逐行看：第 1 行导入起步项目里现成的侧边栏组件。第 3 行，布局组件接收 children，类型是 React.ReactNode，意思是“任何能显示的东西”。外层 div 在手机上竖着排（flex-col），电脑上横着排（md:flex-row）。左边一块固定宽度放 SideNav，右边一块用 grow 占满剩下的空间，{children} 就放在这里。访问 /dashboard/invoices 时，children 就是 invoices 的 page.tsx。
布局可以一层套一层：根布局 app/layout.tsx 包住 app/dashboard/layout.tsx，后者再包住后台的各个页面。根布局是必须有的，而且只有它能写 <html> 和 <body>。
布局还有一个好处叫“局部渲染”：在后台的几个页面之间切换时，只有页面部分会换，侧边栏不会重新渲染。侧边栏里如果有展开的菜单、输入了一半的搜索词，切换页面后都还在。不过这个好处要配合明天学的 Link 组件才看得出来，今天你会发现点侧边栏时整个页面都会闪一下，这正是明天要解决的问题。
跟英文教程最容易犯的错，是一路复制粘贴，页面跑起来了，脑子里什么都没留下。今天给自己定三条规矩：
和 Claude 的分工也按今天起的新规矩来。认识项目、理解概念时，用 Plan 模式让它讲，它不会动你的文件。需要重复性的代码时，比如三个几乎一样的页面，可以让它写，但写完你要逐行读，读完能回答“这一行删掉会怎样”才算看懂。像布局这种今天的核心知识，自己写，写完再请它审查。这样三周后你手里有一个能用的网站，脑子里也有一套能讲清楚的知识。
明天你会继续教程第 5 章，把侧边栏的链接换成 Link，然后正式创建你自己的 dongge-web 项目，把 React 版官网的页面一页页搬过去。
检查 Node.js 版本
Next.js 要求 Node.js 20.9 或更高。打开终端：
node -v看到 v20.9.0 以上（比如 v22.x、v24.x）就可以。如果低于这个版本，用 DAY 01 的方法升级：brew upgrade node。
安装 pnpm
npm install -g pnpm
pnpm -v-g 表示全局安装，装一次以后在任何文件夹都能用。第二行能打印出版本号就说明装好了。
用官方起步项目创建 nextjs-dashboard
cd ~/code
npx create-next-app@latest nextjs-dashboard --example "https://github.com/vercel/next-learn/tree/main/dashboard/starter-example" --use-pnpm--example 后面是起步项目在 GitHub 上的位置，--use-pnpm 表示用 pnpm 安装依赖。整个过程需要一两分钟，最后出现 Success! 就好了。命令以官方教程第 1 章为准，如果教程里的写法变了，照教程的来。
ls ~/code/nextjs-dashboard 能看到 app、public、package.json、pnpm-lock.yaml。启动开发服务器
cd ~/code/nextjs-dashboard
pnpm dev浏览器打开 http://localhost:3000。这个终端窗口要一直开着，关掉网站就停了。要做别的命令，在终端里新开一个标签页。
让 Claude 带你认识项目（Plan 模式）
在 Claude Code 里打开 ~/code/nextjs-dashboard，切到 Plan 模式，把今天 claude 部分的第一条提示词发给它。它只会讲解，不会改文件。一边听讲一边在 VS Code 里打开对应文件看一眼，把“哪几个文件决定了网址”这个答案记到笔记里。
第 2 章：接上全局样式
打开 app/layout.tsx，在第一行加上 import '@/app/ui/global.css'（完整代码见上午第 3 节）。保存后浏览器会自动刷新。
再按教程试一下黑色三角形和 home.module.css 两种写法，亲眼看看 Tailwind 和 CSS Modules 能画出同样的东西。试完可以删掉，不影响后面。
第 3 章：加字体
新建 app/ui/fonts.ts，写入上午第 4 节的 Inter 代码。然后改 app/layout.tsx：
nextjs-dashboard/app/layout.tsx
import '@/app/ui/global.css'
import { inter } from '@/app/ui/fonts'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body className={`${inter.className} antialiased`}>{children}</body>
</html>
)
}接着做教程里的练习：在 fonts.ts 里再导出一个 Lusitana 字体，粗细要 400 和 700，用在首页那段欢迎文字上，然后把 page.tsx 里 {/* <AcmeLogo /> */} 的注释去掉。先自己写，写不出来再展开答案。
nextjs-dashboard/app/ui/fonts.ts
import { Inter, Lusitana } from 'next/font/google'
export const inter = Inter({ subsets: ['latin'] })
export const lusitana = Lusitana({
weight: ['400', '700'],
subsets: ['latin'],
})在 app/page.tsx 里 import { lusitana } from '@/app/ui/fonts'，把欢迎段落的 className 改成 {`${lusitana.className} text-xl text-gray-800 md:text-3xl md:leading-normal`}。AcmeLogo 组件内部也用了 lusitana，所以必须先有这个导出，注释才能去掉。
第 3 章：加首页大图
在 app/page.tsx 顶部加 import Image from 'next/image'，把 {/* Add Hero Images Here */} 那一行换成两张图：
nextjs-dashboard/app/page.tsx（片段）
<Image
src="/hero-desktop.png"
width={1000}
height={760}
className="hidden md:block"
alt="后台页面在电脑上的截图"
/>
<Image
src="/hero-mobile.png"
width={560}
height={620}
className="block md:hidden"
alt="后台页面在手机上的截图"
/>第 4 章：用文件夹建三个页面
mkdir -p app/dashboard/customers app/dashboard/invoices在 app/dashboard/page.tsx 写入上午第 5 节的代码。customers 和 invoices 的页面让 Claude 写样板（用 claude 部分第二条提示词），写完你逐行读一遍：它应该和 dashboard 的页面几乎一样，只是文字不同。
/dashboard、/dashboard/customers、/dashboard/invoices，分别看到三行不同的文字。再打开 /dashboard/abc，应该看到 404 页面。第 4 章：加后台布局
新建 app/dashboard/layout.tsx，这次自己动手敲一遍上午第 6 节的代码，不要复制。敲的时候每写完一行，想一下这一行在做什么。
/ 没有侧边栏，因为首页不在 dashboard 文件夹里。观察一个问题，留给明天
点侧边栏里的 Invoices 和 Customers，注意浏览器标签页上的加载图标：每点一次，整个页面都会重新加载。打开 app/ui/dashboard/nav-links.tsx 看看，链接用的是普通的 <a>。记住这个现象，明天用 Link 改掉它。
提交代码
create-next-app 已经帮你把项目变成了 Git 仓库，并做了第一次提交。在第二个终端标签页里：
cd ~/code/nextjs-dashboard
git add .
git commit -m "完成教程第 1-4 章：样式、字体、图片、布局"
git log --onelinegit log 里能看到两条提交。这个项目只用来学习，不需要推到 GitHub。pnpm: command not found：pnpm 没装好，或者装完没重新打开终端。重新运行 npm install -g pnpm，关掉终端再开一个。ERESOLVE unable to resolve dependency tree：起步项目里有的依赖声明只支持旧版 Next.js，npm 对这种冲突很严格。删掉 node_modules 文件夹，按教程用 pnpm install，pnpm 会按锁文件装好。app/layout.tsx 里没导入 global.css，或者路径写错了。确认第一行是 import '@/app/ui/global.css'，注意 ui 文件夹在 app 里面。Image 组件必须写宽高，值是数字，要用花括号 width={1000}，不能写成 width="1000px"。page.tsx（不是 Page.tsx 或 index.tsx），是否放在正确的文件夹里，以及开发服务器是不是在 nextjs-dashboard 这个文件夹里启动的。在 Next.js 里，文件夹结构怎么决定网址？
app 文件夹里的每一层文件夹对应网址里的一段，比如 app/dashboard/invoices 对应 /dashboard/invoices。但只有文件夹里有 page.tsx，这个网址才能被访问；没有 page.tsx 的文件夹（比如 app/ui）只是普通文件夹，不会变成网址。app/page.tsx 本身对应首页 /。
如果把 app/dashboard/layout.tsx 删掉，三个后台页面还能打开吗？会有什么变化？
还能打开，因为决定网址存在的是 page.tsx，不是 layout.tsx。变化是侧边栏没了，三个页面只剩各自的一行文字。它们仍然会被根布局 app/layout.tsx 包住，所以全局样式和字体还在。
用 next/image 时为什么一定要写 width 和 height？不写会怎样？
Next.js 要靠宽高提前算出图片的比例，在图片还没下载完时就把位置占好，这样图片加载出来后不会把下面的内容往下推，避免布局偏移。用本地图片不写宽高会直接报错。
<a> 换成 Link，并说出客户端跳转和预取让页面变快的原因。[slug] 文件夹做动态路由，一个页面文件服务三个世界的网址，并用 await params 读出网址里的值。loading.tsx 和 not-found.tsx，并用 notFound() 处理不存在的世界。create-next-app 建好 ~/code/dongge-web（TypeScript、Tailwind、App Router、ESLint），推到 GitHub。dongge-react 的类型、数据、展示组件，以及首页、链接页、三个世界页迁移到 dongge-web。昨天你发现点教程侧边栏时整个页面会重新加载。原因是 <a href> 的默认行为：浏览器扔掉当前页面，重新向服务器要一整页，HTML、CSS、JavaScript 全部重来。页面上的状态（比如输入了一半的内容）也跟着丢了。
Next.js 的 Link 组件看起来和 <a> 一样，最后在页面上也会变成一个 <a> 标签，但点击时它会拦住浏览器的默认行为，只去取新页面需要的那部分内容，然后替换掉页面区域。布局、侧边栏原地不动。这叫客户端跳转。
nextjs-dashboard/app/ui/dashboard/nav-links.tsx（片段）
import Link from 'next/link'
<Link
key={link.name}
href={link.href}
className="flex h-[48px] grow items-center justify-center gap-2 rounded-md bg-gray-50 p-3 text-sm font-medium hover:bg-sky-100 hover:text-blue-600 md:flex-none md:justify-start md:p-2 md:px-3"
>
<LinkIcon className="w-6" />
<p className="hidden md:block">{link.name}</p>
</Link>改动只有两处：从 next/link 导入 Link，把 <a> 换成 <Link>，href 写法不变。注意和 React Router 的区别：React Router 的 Link 用 to，Next.js 的 Link 用 href。
Link 还会预取：上线后，当一个 Link 出现在屏幕上，Next.js 会在后台提前把它指向的页面准备好。等你真的点下去，内容已经在手边了，所以感觉几乎是瞬间打开。就像外卖小哥看你常点那家店，提前在店门口等着。开发模式下预取不完全生效，上线后效果最明显。
记住一条：站内跳转用 Link，跳到别的网站（比如你的小红书主页）用普通 <a>，外链没法预取，也不需要。
教程第 5 章的第二个练习是让当前所在页面的链接高亮。要知道“当前在哪个网址”，得用 next/navigation 里的 usePathname：
nextjs-dashboard/app/ui/dashboard/nav-links.tsx（片段）
'use client'
import { usePathname } from 'next/navigation'
import clsx from 'clsx'
export default function NavLinks() {
const pathname = usePathname()
// ……在 Link 的 className 里：
// clsx('基础样式', { 'bg-sky-100 text-blue-600': pathname === link.href })
}usePathname() 返回当前网址的路径部分，比如 /dashboard/invoices。拿它和每个链接的 href 比较，相等就加上高亮的 class，这就是昨天学的 clsx 的用武之地。
文件第一行的 'use client' 很关键。以 use 开头的函数叫 Hook，你在 DAY 29 用过 useState。在 Next.js 里，用 Hook 的组件必须标记成“客户端组件”。为什么要标、什么时候标，是明天的主题，今天先照做。
三个世界的详情页结构完全一样，只是数据不同。DAY 34 你在 React Router 里写过 /world/:id，再用 useParams() 读出网址里的值。Next.js 里的做法是给文件夹名加方括号：
app/world/[slug]/page.tsx
/world/gentleman → slug 是 "gentleman"
/world/street → slug 是 "street"
/world/thai → slug 是 "thai"方括号里的名字随你起，我们叫它 slug。slug 是一个常见术语，意思是“放在网址里的、给人看得懂的短名字”，正好和数据里 slug: 'gentleman' 对上。页面组件会收到一个 params：
dongge-web/app/world/[slug]/page.tsx（结构）
export default async function WorldPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// 用 slug 找到对应的世界……
}对比一下你 DAY 34 的写法。在 React Router 里，网址参数是在组件内部用 Hook 取出来的：
dongge-react 里的写法（对照用）
const { id } = useParams()而在 Next.js 里，参数是从外面“递进来”的：Next.js 在渲染页面之前已经解析好了网址，把结果作为 params 属性交给页面组件。你不用在组件里找网址，只需要打开这个“包裹”。
这里有两个新东西。第一，组件前面有 async，因为 params 是一个 Promise（DAY 22 学的，“一张会兑现的小票”），要用 await 等它兑现，才能拿到 { slug: 'street' }。第二，类型写成 Promise<{ slug: string }>，注意 slug 的类型是 string 而不是你定义的 World，因为访客可以在地址栏里随便输入，比如 /world/boxing。所以拿到 slug 后一定要检查它是不是真的存在。
组件能写成 async，是因为 Next.js 的页面默认在服务器上运行。这在 dongge-react 里是不行的，明天会讲清楚背后的原因。
如果你事先知道只有这三个值，可以再导出一个 generateStaticParams 函数告诉 Next.js，它在构建时就把三个页面提前生成好，访客打开时直接拿现成的：
export function generateStaticParams() {
return worlds.map((world) => ({ slug: world.slug }))
}它返回一个数组，每一项是一个 { slug: ... } 对象，对应一个要提前生成的网址。
访客输入 /world/boxing，找不到这个世界时，调用 notFound()：
import { notFound } from 'next/navigation'
const world = worlds.find((item) => item.slug === slug)
if (!world) {
notFound()
}notFound() 会立刻停止渲染当前页面，改为显示离它最近的 not-found.tsx，并告诉浏览器这是 404。一个额外的好处：TypeScript 知道 notFound() 之后的代码不会在 world 为空时执行，所以后面用 world.name 不会报“可能为 undefined”。
放在 app 根目录的 app/not-found.tsx 还有一个作用：访客访问任何不存在的网址，都会看到它。DAY 35 你给 React 版官网做过 404 页面，今天把它搬到这里。
“离它最近”是什么意思？not-found.tsx 也可以放进子文件夹，比如 app/world/not-found.tsx，这样世界页里调用 notFound() 时，会显示这个更具体的版本，比如写一句“目前只有绅士、街头、泰风三个世界”。子文件夹里没有，就一层层往上找，最后用根目录那个。对你的官网来说，一个根目录的 404 页面就够了。
loading.tsx 是另一个约定文件。页面需要等待（比如 DAY 42 起要查数据库）时，Next.js 会先显示 loading.tsx 的内容，页面准备好了再换上真正的内容。它和页面放在同一个文件夹里，只管这个文件夹及子文件夹的页面：
dongge-web/app/world/[slug]/loading.tsx
export default function Loading() {
return <p className="text-gray-500">正在打开这个世界…</p>
}现在数据写在代码里，几乎不用等，你可能看不到它闪出来；等接上数据库它就有用了。到这里，app 里常用的约定文件你已经认识了四个：page 决定网址存在，layout 是共享外壳，loading 是等待画面，not-found 是找不到时的画面。
从今天起到第 72 天，你的正式项目是 ~/code/dongge-web。运行 npx create-next-app@latest dongge-web 时，它会先问你是否使用推荐的默认设置。推荐设置正好是我们要的：TypeScript、ESLint、Tailwind CSS、App Router，外加一个 AGENTS.md。如果你选择自己定制，各项这样答：
| 问题 | 回答 | 原因 |
|---|---|---|
| TypeScript | Yes | DAY 25 起一直在用 |
| Linter | ESLint | 检查代码里的常见错误 |
| React Compiler | No | 自动优化性能的新工具，现在用不上 |
| Tailwind CSS | Yes | DAY 32 学过，而且是 v4 |
src/ directory | No | 让 app 直接放在根目录，和教程一致 |
| App Router | Yes | 这门课学的就是 App Router |
| customize import alias | No | 保留默认的 @/* |
| AGENTS.md | Yes | 给 Claude 这类编程助手看的说明 |
这几个选项的问法可能随版本变化，意思对上就行，以官方文档为准。建好之后，几个值得认识的文件：
app/layout.tsx 和 app/page.tsx：根布局和首页，昨天在教程里见过。app/globals.css：开头是 @import "tailwindcss";，这就是 Tailwind v4 写法。Next.js 项目里 Tailwind 通过 postcss.config.mjs 里的 @tailwindcss/postcss 插件工作，不是 Vite 项目用的 @tailwindcss/vite，但你写 class 的方式完全一样，也不需要 tailwind.config.js。AGENTS.md 和 CLAUDE.md：Next.js 更新很快，Claude 训练时见过的可能是旧写法。这两个文件提醒编程助手先去读 node_modules/next/dist/docs/ 里和你安装版本一致的官方文档。Claude Code 会自动读 CLAUDE.md，所以保留它们。.gitignore：已经写好了忽略 node_modules、.next（构建产物）和所有 .env 开头的文件，后面存数据库密码时会用到这一点。再看 package.json 里的几个脚本，以后天天用：npm run dev 启动开发服务器，改了代码自动刷新；npm run build 按上线的标准完整构建一遍，类型错误、页面报错都会在这里暴露出来；npm run start 运行构建好的版本，用来在本机模拟线上；npm run lint 运行 ESLint 检查代码。开发时主要用 dev，每次准备提交重要改动前跑一次 lint 和 build，能提前抓住很多上线后才会发现的问题。
搬家之前先列清单。下面是 dongge-react 里的东西在 dongge-web 里的新位置：
| dongge-react | dongge-web | 要改什么 |
|---|---|---|
src/main.tsx、App.tsx 里的路由表 | 不需要了 | app 的文件夹结构就是路由 |
index.html 里的 <title> | app/layout.tsx 里的 metadata | 改成导出一个对象 |
src/types.ts | lib/types.ts | 不用改 |
src/data/*.ts | lib/data/*.ts | 不用改 |
src/components/*.tsx | components/*.tsx | 导入路径改成 @/lib/... |
| 首页组件 | app/page.tsx | 重写成页面 |
/world/:id 页面 | app/world/[slug]/page.tsx | useParams 换成 await params |
| 链接页 | app/links/page.tsx | 重写成页面 |
| 404 页面 | app/not-found.tsx | 基本照搬 |
| 测试小游戏 | app/quiz/page.tsx | 明天处理 |
React Router 的 <Link to> | next/link 的 <Link href> | 改导入和属性名 |
public/ 里的图片 | public/ | 原样复制，网址不变 |
| 自定义 CSS（如三个世界的颜色变量） | app/globals.css | 贴在 @import 那行下面 |
为什么 types.ts 和数据文件不用改？因为它们是纯 TypeScript，不依赖 Vite 也不依赖 React Router。只要保持“lib/types.ts 在 lib/data/ 的上一层”这个相对位置，数据文件里的 import type { Look } from '../types' 依然成立。组件文件就不一样了，它们原来在 src/components/，'../types' 指向 src/types.ts；搬到 components/ 后，'../types' 会指向项目根目录下一个不存在的文件，所以要改成 '@/lib/types'。
今天只搬“展示型”的东西：只负责把数据显示出来、不用 useState 的组件和页面。测试小游戏、风格切换、世界筛选这些要响应点击的组件，明天学完客户端组件再搬。今天的页面里先不要导入它们。
昨天在教程里，app/dashboard/layout.tsx 给后台的三个页面加了共用的侧边栏。你的官网也有同样的需求：三个世界的页面，顶部都想放一排“绅士 / 街头 / 泰风”的切换按钮，方便访客在世界之间来回看。
做法一样：在 app/world 文件夹里放一个 layout.tsx。它会包住 app/world 下面所有的页面，也就是三个世界的详情页；首页、链接页不在这个文件夹里，就不受影响。
dongge-web/app/world/layout.tsx
import Link from 'next/link'
import { worlds } from '@/lib/data/worlds'
export default function WorldLayout({ children }: { children: React.ReactNode }) {
return (
<div className="space-y-6">
<div className="flex gap-2">
{worlds.map((world) => (
<Link
key={world.slug}
href={`/world/${world.slug}`}
className="rounded-full border px-3 py-1 text-sm hover:bg-gray-50"
>
{world.name}
</Link>
))}
</div>
{children}
</div>
)
}这时访问 /world/street，页面其实是三层套在一起的：最外层是根布局（导航栏和 main），中间是世界布局（三个切换按钮），最里面才是 [slug]/page.tsx 渲染的街头内容。可以把它想成俄罗斯套娃，每一层只关心自己那一圈，不用知道里面装的是什么。
在三个世界之间切换时，根布局和世界布局都不会重新渲染，只有最里面的页面换掉。以后如果你想在世界布局里加一个背景音乐开关，切换世界时音乐也不会断。
还要注意一点：app/world 文件夹里没有 page.tsx，所以直接访问 /world 会是 404。布局本身不会让网址存在，这再次印证了“有 page 网址才存在”这条规则。现在没有人会直接访问 /world，保持 404 就好。
最后说一下 loading.tsx 在这个套娃里的位置：Next.js 会把它放在布局和页面之间，所以页面还在准备时，导航栏和世界切换按钮已经显示出来了，只有页面那一块显示“正在打开这个世界…”。访客不会看到一片空白，这就是布局和等待画面配合的好处。
教程第 5 章：换成 Link，再高亮当前链接
回到 ~/code/nextjs-dashboard，运行 pnpm dev。打开 app/ui/dashboard/nav-links.tsx，按上午第 1 节把 <a> 换成 <Link>。
接着按教程在文件顶部加 'use client'，导入 usePathname 和 clsx，把 Link 的 className 改成 clsx(原来的字符串, { 'bg-sky-100 text-blue-600': pathname === link.href })。先自己写，卡住了对照教程原文。
git add .
git commit -m "完成教程第 5 章：Link 和当前链接高亮"教程先跟到这里。停掉教程的服务器（在那个终端按 Ctrl + C）。
创建 dongge-web
cd ~/code
npx create-next-app@latest dongge-web出现 Would you like to use the recommended Next.js defaults? 时选 Yes, use recommended defaults。如果问题和这里不一样，选自己定制，按上午第 5 节的表格回答。
Success! Created dongge-web。跑起来看一眼
cd ~/code/dongge-web
npm run dev打开 http://localhost:3000，能看到 Next.js 的欢迎页。在 VS Code 里打开 app/globals.css、AGENTS.md、CLAUDE.md 各看一眼，对照上午第 5 节。
让 Claude 出迁移方案（Plan 模式）
在 Claude Code 里打开 ~/code/dongge-web，切到 Plan 模式，发送 claude 部分的第一条提示词。把它的方案和上午第 6 节的迁移地图对照，有不一致的地方问它为什么。方案确认前，不要让它改文件。
复制类型、数据、组件和图片
在第二个终端标签页里，确认你在 ~/code/dongge-web：
mkdir -p components lib
cp ~/code/dongge-react/src/types.ts lib/types.ts
cp -R ~/code/dongge-react/src/data lib/data
cp -R ~/code/dongge-react/src/components/. components/
cp -R ~/code/dongge-react/public/. public/
ls lib lib/data componentscp -R 连同文件夹里的内容一起复制；components/. 末尾的点表示“复制这个文件夹里面的所有东西”，而不是把文件夹本身套进去。如果你在 dongge-react 里还有别的自定义 CSS（比如三个世界的颜色变量），把那些规则复制到 app/globals.css 的 @import "tailwindcss"; 这一行下面。
lib 里有 types.ts 和 data 文件夹，components 里有 LookCard.tsx、PlatformButton.tsx 等文件。让 Claude 改导入路径，你来审
发送 claude 部分的第二条提示词，让 Claude 只改 components 里的导入路径。改完后自己看改动：
git diff components每一处改动都应该是 '../types' 变成 '@/lib/types'、'../data/xxx' 变成 '@/lib/data/xxx' 这一类。组件里如果用了 React Router 的 Link，应该换成 next/link，并把 to= 改成 href=。除了这些，出现任何逻辑改动都要问清楚原因。
写根布局和导航
新建 components/Nav.tsx：
dongge-web/components/Nav.tsx
import Link from 'next/link'
import { worlds } from '@/lib/data/worlds'
export default function Nav() {
return (
<header className="border-b">
<nav className="mx-auto flex max-w-3xl flex-wrap items-center gap-4 px-4 py-3 text-sm">
<Link href="/" className="font-bold">
三岁的东哥
</Link>
{worlds.map((world) => (
<Link key={world.slug} href={`/world/${world.slug}`} className="hover:underline">
{world.name}
</Link>
))}
<Link href="/links" className="hover:underline">
链接
</Link>
<Link href="/quiz" className="hover:underline">
测试
</Link>
</nav>
</header>
)
}然后把 app/layout.tsx 整个换成下面的内容。注意 lang 改成了 zh-CN，告诉浏览器和搜索引擎这是中文页面：
dongge-web/app/layout.tsx
import type { Metadata } from 'next'
import { Geist } from 'next/font/google'
import Nav from '@/components/Nav'
import './globals.css'
const geistSans = Geist({
variable: '--font-geist-sans',
subsets: ['latin'],
})
export const metadata: Metadata = {
title: '三岁的东哥',
description: '在外面是绅士、拳手、潮男，在你面前三岁。',
}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="zh-CN" className={`${geistSans.variable} h-full antialiased`}>
<body className="flex min-h-full flex-col">
<Nav />
<main className="mx-auto w-full max-w-3xl flex-1 px-4 py-8">{children}</main>
</body>
</html>
)
}metadata 取代了 index.html 里的 <title> 和描述，Next.js 会自动把它放进页面的 <head>。Geist 是模板自带的英文字体，中文会用系统字体显示，这是故意的：中文字体文件很大，DAY 65 做性能优化时再考虑。
写首页
dongge-web/app/page.tsx
import Link from 'next/link'
import LookCard from '@/components/LookCard'
import { looks } from '@/lib/data/looks'
import { worlds } from '@/lib/data/worlds'
export default function Home() {
return (
<div className="space-y-10">
<section>
<h1 className="text-3xl font-bold">三岁的东哥</h1>
<p className="mt-2 text-gray-600">在外面是绅士、拳手、潮男，在你面前三岁。</p>
</section>
<section>
<h2 className="text-xl font-semibold">三个世界</h2>
<ul className="mt-4 grid gap-4 sm:grid-cols-3">
{worlds.map((world) => (
<li key={world.slug}>
<Link
href={`/world/${world.slug}`}
className="block rounded-xl border p-4 hover:bg-gray-50"
>
<p className="text-lg font-semibold">{world.name}</p>
<p className="text-sm text-gray-500">给你{world.feeling}</p>
</Link>
</li>
))}
</ul>
</section>
<section>
<h2 className="text-xl font-semibold">最近的穿搭</h2>
<div className="mt-4 grid gap-4 sm:grid-cols-2">
{looks.map((look) => (
<LookCard key={look.id} look={look} />
))}
</div>
</section>
</div>
)
}如果你在 DAY 33 做的首页结构不一样（比如用了 Section、Avatar、Intro 组件），照你原来的结构写，只要记住三件事：组件从 @/components/... 导入，数据从 @/lib/data/... 导入，站内链接用 next/link。
写三个世界的详情页（动态路由）
zsh 会把方括号当成特殊符号，所以建文件夹时路径要加引号：
mkdir -p "app/world/[slug]"这个页面是今天的核心，自己敲，不要复制。敲完再对照：
dongge-web/app/world/[slug]/page.tsx
import { notFound } from 'next/navigation'
import LookCard from '@/components/LookCard'
import { looks } from '@/lib/data/looks'
import { worlds } from '@/lib/data/worlds'
export function generateStaticParams() {
return worlds.map((world) => ({ slug: world.slug }))
}
export default async function WorldPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const world = worlds.find((item) => item.slug === slug)
if (!world) {
notFound()
}
const worldLooks = looks.filter((look) => look.world === world.slug)
return (
<div className="space-y-6">
<header>
<p className="text-sm text-gray-500">给你{world.feeling}</p>
<h1 className="text-3xl font-bold">{world.name}</h1>
<p className="mt-2 text-gray-600">{world.tagline}</p>
</header>
{worldLooks.length === 0 ? (
<p className="text-gray-500">这个世界的穿搭还在路上。</p>
) : (
<div className="grid gap-4 sm:grid-cols-2">
{worldLooks.map((look) => (
<LookCard key={look.id} look={look} />
))}
</div>
)}
</div>
)
}再新建 app/world/[slug]/loading.tsx，内容见上午第 4 节。
/world/street，只显示街头的两套穿搭。手动访问 /world/boxing，看到 404。加世界布局（嵌套布局）
新建 app/world/layout.tsx，内容见上午第 7 节。写完后在三个世界之间来回点。
/world 是 404。写链接页和 404 页
dongge-web/app/links/page.tsx
import type { Metadata } from 'next'
import PlatformButton from '@/components/PlatformButton'
import { platforms } from '@/lib/data/platforms'
export const metadata: Metadata = {
title: '链接 | 三岁的东哥',
}
export default function LinksPage() {
return (
<div className="mx-auto max-w-sm space-y-6 text-center">
<h1 className="text-2xl font-bold">在这些地方找到我</h1>
<div className="flex flex-col gap-3">
{platforms.map((platform) => (
<PlatformButton key={platform.id} name={platform.name} url={platform.url} />
))}
</div>
</div>
)
}页面里也可以导出 metadata，它会覆盖根布局里的标题。别忘了把 lib/data/platforms.ts 里的 https://example.com/... 换成你自己的小红书、TikTok、Facebook、Instagram 主页链接。
dongge-web/app/not-found.tsx
import Link from 'next/link'
export default function NotFound() {
return (
<div className="space-y-4 text-center">
<h1 className="text-2xl font-bold">这里什么都没有</h1>
<p className="text-gray-600">可能是网址打错了，也可能这一页还没做好。</p>
<Link href="/" className="inline-block rounded-full bg-black px-5 py-2 text-white">
回到首页
</Link>
</div>
)
}如果你 DAY 35 写的 404 文案更好，用你自己的。
/links 显示四个平台按钮，浏览器标签页标题变成“链接 | 三岁的东哥”；导航里的“测试”现在会进 404，明天补上。检查、提交、推到 GitHub
先让 ESLint 和构建都过一遍：
npm run lint
npm run buildnpm run build 最后会列出所有页面，/world/[slug] 下面应该列出 gentleman、street、thai 三个，这就是 generateStaticParams 的效果。然后提交并推到 GitHub（DAY 02 你已经用 gh 登录过）：
git add .
git commit -m "迁移首页、世界页、链接页和 404 页"
gh repo create dongge-web --private --source=. --remote=origin --pushdongge-web 仓库和你的两次提交。今天先不部署到 Vercel，DAY 54 连同数据库一起上线。mkdir 报 zsh: no matches found: app/world/[slug]：zsh 把方括号当成了通配符。给路径加上引号：mkdir -p "app/world/[slug]"。在 VS Code 里右键新建文件夹则没有这个问题。Module not found: Can't resolve '../types'：组件搬了位置，相对路径失效了。改成 @/lib/types 这种从根目录出发的写法。Property 'slug' does not exist on type 'Promise...'：你直接写了 params.slug。params 是 Promise，要先 const { slug } = await params，并且组件前面要加 async。usePathname 或 useState 只能在客户端组件里用：你导入了一个用了 Hook 的组件。今天先别在页面里用它；如果是教程里的 nav-links.tsx，检查第一行有没有 'use client'。明天会系统讲。react-router-dom 导入 Link，属性是不是还写成 to。Next.js 里要从 next/link 导入，属性是 href。layout 和 page 有什么区别？
page.tsx 是某个网址独有的内容，有它这个网址才存在。layout.tsx 是外壳，包住同一文件夹及子文件夹里的所有页面，通过 children 把页面放进去，适合放导航、侧边栏这类多个页面共用的部分。在同一个布局下的页面之间跳转时，布局不会重新渲染，状态会保留；页面则每次换网址都会换掉。根布局必须有，并且要包含 <html> 和 <body>。
访客在地址栏输入 /world/boxing，会看到什么？是你代码里的哪几行决定的？
会看到 app/not-found.tsx 的内容，浏览器收到 404。决定它的是世界页里的 worlds.find(...) 找不到 boxing，返回 undefined，于是执行 if (!world) { notFound() }，Next.js 停止渲染这个页面，改为显示最近的 not-found 页面。
为什么站内跳转用 Link 比用 <a> 快？跳到你的小红书主页该用哪个？
Link 做的是客户端跳转，只替换页面区域，不重新加载整个网页，布局和状态都保留；上线后它还会预取出现在屏幕上的链接，点下去时内容已经准备好了。跳到小红书这种外部网站用普通 <a>，外链不能预取，也不存在“只换一部分”。
"use client"。"use client" 是一道边界：它会把这个文件和它导入的组件都带进浏览器，所以要尽量放在组件树的末端。昨天有两个地方没解释：世界页的组件前面可以写 async，而教程里的导航组件第一行必须写 'use client'。今天就把这件事讲透，这是 Next.js 和你之前写的 React 最大的不同。
打个比方。一家餐厅有后厨和餐桌。后厨在里面，有冰箱、刀具、供货商的电话，客人看不到也进不去；菜在后厨做好，端出来就是成品。餐桌上有些菜是半成品，比如一锅小火锅，端上桌后客人自己调火、下菜，锅要跟着客人的动作变化。
app 里，所有组件默认都是服务端组件。localStorage 这类只有浏览器才有的功能。要让一个组件变成客户端组件，在文件第一行写 "use client"。你在 dongge-react 里写的所有组件，其实都是“客户端组件”，因为那个项目根本没有服务器参与渲染，所有东西都在浏览器里跑。所以 useState、onClick 随便用。到了 Next.js，默认情况反过来了：先假设组件在后厨，需要和访客互动的，才搬到餐桌上。
访客第一次打开 /quiz 时，大致发生了这几件事：
服务端组件的结果会以一种紧凑的数据格式（RSC Payload）发给浏览器，里面有服务端组件渲染好的内容、客户端组件该出现的位置，以及服务端传给客户端组件的数据。你不需要记住这个格式，只要知道：服务端组件在浏览器里只留下结果，客户端组件在浏览器里留下的是会动的代码。
这带来两个直接结论。第一，服务端组件越多，访客要下载的 JavaScript 越少，手机上打开越快。第二，客户端组件因为要在服务器上先跑一遍，所以渲染时不能直接用 window、localStorage，服务器上没有这些东西，这一点在第 6 节细讲。
判断方法很简单，看组件里有没有下面四样东西，有任何一样就是客户端组件：
| 需要的东西 | 例子 |
|---|---|
| 状态 | useState：记住选了哪个世界、答到第几题 |
| 事件 | onClick、onChange：点按钮、打字 |
| 生命周期 | useEffect：组件出现后做点什么 |
| 浏览器专属功能 | localStorage、window、usePathname 这类读取当前浏览器状态的 Hook |
反过来，要查数据库、用密钥、只是把数据显示出来的组件，留在服务端。拿你的官网逐个过一遍：
| 组件 | 放在哪 | 理由 |
|---|---|---|
所有 page.tsx、layout.tsx | 服务端 | 负责取数据、拼页面 |
LookCard、PlatformButton、Nav | 服务端 | 只显示内容，外链用普通 <a> 就能点 |
NavLinks（导航高亮） | 客户端 | 要用 usePathname 知道当前网址 |
LookFilter（只看某个世界） | 客户端 | 要记住当前选的是哪个世界 |
StyleSwitcher（风格切换） | 客户端 | 要记住选择，还要读写 localStorage |
Quiz（测试小游戏） | 客户端 | 见下面 |
测试小游戏是最典型的客户端组件。它要记住“当前第几题”和“已经选了什么”，这是状态；每点一个选项就要更新界面，这是事件；整个过程都在访客的手机上一步步进行，不需要每点一下都去问服务器。如果把它留在服务端，服务端组件没有 useState，也不能响应点击，Next.js 会直接报错。
注意 PlatformButton：它虽然能“点”，但点的是一个普通链接，跳转是浏览器自己完成的，组件本身不需要写 onClick，所以它可以留在服务端。能点不等于需要客户端组件，要看你有没有自己写事件处理。
"use client" 写在文件第一行，作用于整个文件。更重要的是，它划了一道边界：这个文件，以及它导入并渲染的所有组件，都会被打包送进浏览器。所以你 DAY 31 写的测试小游戏如果由 Quiz、QuestionCard、ProgressBar、ResultCard 几个组件组成，只需要在最外层的 Quiz.tsx 写 "use client"，里面导入的几个子组件会自动跟着变成客户端组件，不用每个都写。
既然边界以下的东西都会进浏览器，那边界就应该尽量往下放，只包住真正需要互动的那一小块。常见的错误是图省事，在 app/page.tsx 顶部写一个 "use client"，整个首页都变成了客户端组件。后果有三个：首页的代码全部发给浏览器，变重了；页面不能再写 async，DAY 42 没法直接查数据库；页面也不能再导出 metadata，只有服务端组件才能设置标题和描述。
正确的做法是像导航栏这样拆开：Nav 留在服务端，只把需要知道当前网址的那部分拆成 NavLinks 客户端组件。
还有一个很有用的例外：通过 children 传进客户端组件的服务端组件，仍然是服务端组件。比如风格切换组件要包住整个页面内容：
dongge-web/app/layout.tsx（片段）
<StyleSwitcher>
<main className="mx-auto w-full max-w-3xl flex-1 px-4 py-8">{children}</main>
</StyleSwitcher>StyleSwitcher 是客户端组件，但它包住的页面是在布局（服务端）里写好、作为 children 递进去的。这些页面在服务器上已经渲染成结果，StyleSwitcher 只是把结果摆在自己的盒子里，并不会把页面的代码拉进浏览器。区别在于“谁导入了谁”：在客户端组件文件里 import 的组件会进浏览器，从外面当 children 递进来的不会。
世界筛选组件需要穿搭数据。最自然的做法是让服务端页面拿到数据，再通过 props 交给客户端组件：
dongge-web/app/page.tsx（片段）
import LookFilter from '@/components/LookFilter'
import { looks } from '@/lib/data/looks'
// 页面是服务端组件，LookFilter 是客户端组件
<LookFilter looks={looks} />现在数据来自代码里的数组，看不出区别；DAY 42 换成数据库以后，页面在服务器上查数据库，把结果交给 LookFilter，数据库的连接和密码始终留在后厨，浏览器只收到那几条穿搭。
传给客户端组件的 props 有两个要求。第一，必须能序列化，也就是能变成一段文本通过网络发出去：字符串、数字、布尔值、普通对象、数组、日期都可以；普通函数不行，因为函数没法“打包寄出去”。第二，传过去的东西访客都能看到，打开开发者工具就能翻出来。所以只传界面需要的字段，DAY 45 讲安全时还会回到这一点。
DAY 30 你用 localStorage 记住了访客选的风格，读取时很可能写的是 useState(() => localStorage.getItem('style') ?? 'gentleman')。在 Vite 项目里这没问题，搬到 Next.js 会报错：localStorage is not defined。原因就是第 2 节说的，客户端组件会先在服务器上渲染一次，而服务器上没有 localStorage。
就算你判断“在服务器上就用默认值”，也会有新问题：服务器按“绅士”渲染出 HTML，浏览器一读 localStorage 发现是“街头”，两边画出的内容不一样，React 会报水合不匹配（hydration mismatch）的错误。
React 为“读取组件外部的数据源”准备了一个专门的 Hook：useSyncExternalStore。它让你分别告诉 React：在服务器上用什么值、在浏览器里怎么读、数据变了怎么通知。这段代码有点绕，属于典型的样板代码，今天让 Claude 写，你负责逐行读懂：
dongge-web/lib/use-saved-world.ts
import { useSyncExternalStore } from 'react'
import type { World } from '@/lib/types'
const KEY = 'dongge-style'
const listeners = new Set<() => void>()
function subscribe(listener: () => void) {
listeners.add(listener)
return () => {
listeners.delete(listener)
}
}
function getSnapshot(): World {
const saved = localStorage.getItem(KEY)
return saved === 'street' || saved === 'thai' ? saved : 'gentleman'
}
function getServerSnapshot(): World {
return 'gentleman'
}
export function useSavedWorld() {
const world = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
function setWorld(next: World) {
localStorage.setItem(KEY, next)
listeners.forEach((listener) => listener())
}
return [world, setWorld] as const
}逐段看：listeners 是一个集合，存着“数据变了要通知谁”。subscribe 由 React 调用，把 React 的通知函数放进集合，并返回一个“取消订阅”的函数。getSnapshot 在浏览器里读取 localStorage，只认 street 和 thai，其他情况一律当作 gentleman，这样就算有人手动改了存储里的值也不会出错。getServerSnapshot 告诉 React 在服务器上和水合时都先用 gentleman，保证两边一致；水合完成后 React 会再用 getSnapshot 读一次真实的值，发现不一样就重新渲染。最后 useSavedWorld 返回一个和 useState 用法一样的数组：当前值和修改函数。修改函数先写进 localStorage，再挨个通知，React 收到通知就会重新读取。
你可能会想，能不能在 useEffect 里读 localStorage 再调用 setState？能跑，但会先闪一下默认风格，而且新版 ESLint 的规则 react-hooks/set-state-in-effect 会把它标成错误。以后遇到“读取浏览器里的东西”这类需求，记住有 useSyncExternalStore 这个正路就够了。
先分类，再让 Claude 审（Plan 模式）
打开 ~/code/dongge-web/components 和 ~/code/dongge-react/src/components，在笔记里列一张表：每个组件一行，写上“服务端”或“客户端”和一句理由。写完后切到 Plan 模式，发送 claude 部分的第一条提示词，让 Claude 审查你的分类。有分歧的地方，一定要问到你能说出谁对为止。
拆出导航高亮：NavLinks
新建客户端组件：
dongge-web/components/NavLinks.tsx
'use client'
import Link from 'next/link'
import { usePathname } from 'next/navigation'
type NavLink = {
href: string
label: string
}
export default function NavLinks({ links }: { links: NavLink[] }) {
const pathname = usePathname()
return (
<>
{links.map((link) => (
<Link
key={link.href}
href={link.href}
className={pathname === link.href ? 'font-semibold underline' : 'hover:underline'}
>
{link.label}
</Link>
))}
</>
)
}然后改 components/Nav.tsx，它继续留在服务端，负责准备链接数据，再交给 NavLinks：
dongge-web/components/Nav.tsx
import Link from 'next/link'
import NavLinks from '@/components/NavLinks'
import { worlds } from '@/lib/data/worlds'
export default function Nav() {
const links = [
...worlds.map((world) => ({ href: `/world/${world.slug}`, label: world.name })),
{ href: '/links', label: '链接' },
{ href: '/quiz', label: '测试' },
]
return (
<header className="border-b">
<nav className="mx-auto flex max-w-3xl flex-wrap items-center gap-4 px-4 py-3 text-sm">
<Link href="/" className="font-bold">
三岁的东哥
</Link>
<NavLinks links={links} />
</nav>
</header>
)
}/world/street，导航里的“街头”变粗并带下划线；切到“链接”，高亮跟着走。测试小游戏的数据和计分（核心逻辑你来写）
新建 lib/quiz.ts。题目数据可以直接用你 DAY 23 写的 6 道题，这里先放 3 道做示范。计分函数 scoreQuiz 是核心逻辑，你自己写：输入一个数组，里面是每道题选中的世界，返回得分最高的世界；同分时按绅士、街头、泰风的顺序取前面那个（DAY 18 你讨论过同分问题，如果你当时定了别的规则，就用你的规则）。
dongge-web/lib/quiz.ts
import type { World } from '@/lib/types'
export type QuizOption = {
text: string
world: World
}
export type QuizQuestion = {
id: number
question: string
options: QuizOption[]
}
export const quizQuestions: QuizQuestion[] = [
{
id: 1,
question: '周末下午，你更想怎么过？',
options: [
{ text: '找个安静的地方，看他打一局斯诺克', world: 'gentleman' },
{ text: '去滑板公园，看他练新动作', world: 'street' },
{ text: '陪他去拳馆，坐在台边等他练完', world: 'thai' },
],
},
{
id: 2,
question: '你加班到很晚，最希望收到哪条消息？',
options: [
{ text: '“我在楼下，车里有热水。”', world: 'gentleman' },
{ text: '“下班了吗？带你去兜一圈风。”', world: 'street' },
{ text: '“别走夜路，我过来接你。”', world: 'thai' },
],
},
{
id: 3,
question: '他身上哪件东西最让你记住？',
options: [
{ text: '熨平的衬衫和擦亮的皮鞋', world: 'gentleman' },
{ text: '磨旧的 Vans 和宽松的卫衣', world: 'street' },
{ text: '缠手带和泰拳短裤', world: 'thai' },
],
},
]
export function scoreQuiz(answers: World[]): World {
// 你来写：统计每个世界被选了几次，返回次数最多的那个
}export function scoreQuiz(answers: World[]): World {
const scores: Record<World, number> = { gentleman: 0, street: 0, thai: 0 }
for (const world of answers) {
scores[world] += 1
}
const order: World[] = ['gentleman', 'street', 'thai']
let best = order[0]
for (const world of order) {
if (scores[world] > scores[best]) {
best = world
}
}
return best
}Record<World, number> 表示“键是三个世界、值是数字的对象”。比较时用大于号而不是大于等于，所以同分时保留先出现的那个，也就是按 order 的顺序取前面的。
测试小游戏组件（客户端）和页面（服务端）
如果你 DAY 31 的 React 版测试拆成了几个组件，把它们复制到 components/quiz/，只在最外层组件第一行加 'use client'，导入路径改成 @/lib/...。想对照的话，下面是一个把所有部分写在一起的精简版：
dongge-web/components/Quiz.tsx
'use client'
import { useState } from 'react'
import Link from 'next/link'
import type { World } from '@/lib/types'
import { quizQuestions, scoreQuiz } from '@/lib/quiz'
import { worlds } from '@/lib/data/worlds'
export default function Quiz() {
const [current, setCurrent] = useState(0)
const [answers, setAnswers] = useState<World[]>([])
function choose(world: World) {
setAnswers([...answers, world])
setCurrent(current + 1)
}
function restart() {
setAnswers([])
setCurrent(0)
}
if (answers.length === quizQuestions.length) {
const result = scoreQuiz(answers)
const world = worlds.find((item) => item.slug === result)
return (
<div className="space-y-4 rounded-2xl border p-6 text-center">
<p className="text-sm text-gray-500">你现在最需要的是</p>
<h2 className="text-3xl font-bold">{world?.name}东哥</h2>
<p className="text-gray-600">他能给你{world?.feeling}。</p>
<div className="flex justify-center gap-3">
<Link href={`/world/${result}`} className="rounded-full bg-black px-5 py-2 text-white">
去看看这个世界
</Link>
<button type="button" onClick={restart} className="rounded-full border px-5 py-2">
再测一次
</button>
</div>
</div>
)
}
const question = quizQuestions[current]
return (
<div className="space-y-4">
<p className="text-sm text-gray-500">
第 {current + 1} / {quizQuestions.length} 题
</p>
<progress value={current} max={quizQuestions.length} className="h-2 w-full" />
<h2 className="text-xl font-semibold">{question.question}</h2>
<div className="flex flex-col gap-3">
{question.options.map((option) => (
<button
key={option.text}
type="button"
onClick={() => choose(option.world)}
className="rounded-xl border p-4 text-left hover:bg-gray-50"
>
{option.text}
</button>
))}
</div>
</div>
)
}页面本身是服务端组件，负责标题、说明和 metadata，把互动的部分交给 Quiz：
dongge-web/app/quiz/page.tsx
import type { Metadata } from 'next'
import Quiz from '@/components/Quiz'
export const metadata: Metadata = {
title: '你最需要哪个东哥 | 三岁的东哥',
}
export default function QuizPage() {
return (
<div className="mx-auto max-w-md space-y-6">
<h1 className="text-2xl font-bold">你最需要哪个东哥</h1>
<p className="text-gray-600">凭第一感觉选，不用想太久。</p>
<Quiz />
</div>
)
}/quiz，能一题一题答完，看到结果和“去看看这个世界”按钮，点“再测一次”回到第一题。做两个故意出错的实验
实验一：删掉 components/Quiz.tsx 第一行的 'use client'，保存，看浏览器和终端的报错，大意是 useState 只能在客户端组件里用。读懂后加回去。
实验二：在 app/quiz/page.tsx 第一行加 'use client'，看报错，大意是客户端组件不能导出 metadata。读懂后删掉。把两条报错原文记进笔记，以后见到就知道是边界放错了。
世界筛选：LookFilter
dongge-web/components/LookFilter.tsx
'use client'
import { useState } from 'react'
import LookCard from '@/components/LookCard'
import type { Look, World } from '@/lib/types'
import { worlds } from '@/lib/data/worlds'
function pill(active: boolean) {
return active
? 'rounded-full bg-black px-3 py-1 text-sm text-white'
: 'rounded-full border px-3 py-1 text-sm'
}
export default function LookFilter({ looks }: { looks: Look[] }) {
const [selected, setSelected] = useState<World | 'all'>('all')
const shown = selected === 'all' ? looks : looks.filter((look) => look.world === selected)
return (
<div className="space-y-4">
<div className="flex flex-wrap gap-2">
<button type="button" onClick={() => setSelected('all')} className={pill(selected === 'all')}>
全部
</button>
{worlds.map((world) => (
<button
key={world.slug}
type="button"
onClick={() => setSelected(world.slug)}
className={pill(selected === world.slug)}
>
{world.name}
</button>
))}
</div>
{shown.length === 0 ? (
<p className="text-gray-500">这个世界的穿搭还在路上。</p>
) : (
<div className="grid gap-4 sm:grid-cols-2">
{shown.map((look) => (
<LookCard key={look.id} look={look} />
))}
</div>
)}
</div>
)
}然后在 app/page.tsx 里，把“最近的穿搭”下面那个 div 和里面的 looks.map 换成 <LookFilter looks={looks} />，文件顶部加上 import LookFilter from '@/components/LookFilter'，不再用到的 LookCard 导入删掉。注意 LookCard 没有写 'use client'，但它被客户端组件导入了，所以在首页它会跟着进浏览器；而在世界页里它是被服务端页面导入的，仍然留在服务端。同一个组件，放在边界哪一边由“谁导入它”决定。
风格切换：Claude 写样板，你读懂再用
发送 claude 部分的第二条提示词，让 Claude 按上午第 6 节生成 lib/use-saved-world.ts。拿它的代码和课件对照，逐行说出每一行的作用，说不出来就追问。然后你自己写 components/StyleSwitcher.tsx：
dongge-web/components/StyleSwitcher.tsx
'use client'
import { worlds } from '@/lib/data/worlds'
import { useSavedWorld } from '@/lib/use-saved-world'
export default function StyleSwitcher({ children }: { children: React.ReactNode }) {
const [style, setStyle] = useSavedWorld()
return (
<div className={`theme-${style} flex flex-1 flex-col`}>
<div className="mx-auto flex w-full max-w-3xl gap-3 px-4 pt-4 text-sm">
<span className="text-gray-500">风格</span>
{worlds.map((world) => (
<button
key={world.slug}
type="button"
onClick={() => setStyle(world.slug)}
className={style === world.slug ? 'font-semibold underline' : 'text-gray-500 hover:underline'}
>
{world.name}
</button>
))}
</div>
{children}
</div>
)
}在 app/layout.tsx 里导入它，用它包住 <main>（写法见上午第 4 节的片段）。theme-gentleman、theme-street、theme-thai 三个 class 的颜色规则，用你 DAY 09 定的那三套，放进 app/globals.css；如果你当时的 class 名不一样，把组件里的 theme-${style} 改成你的命名。
看看客户端组件也在服务器上渲染过
打开 /quiz，右键选“查看网页源代码”，按 Cmd + F 搜第一题的文字“周末下午”。能搜到，说明测试小游戏虽然是客户端组件，初始画面也是在服务器上生成好、写在 HTML 里发过来的。这就是上午第 2 节说的第 2 步。
检查、提交、推送
npm run lint
npm run build
git add .
git commit -m "完成官网迁移：测试、筛选、导航高亮、风格切换改为客户端组件"
git pushlint 没有报错，build 成功，GitHub 上能看到新提交。到这里，React 版官网的功能在 dongge-web 里全部复原了。useState、useEffect 或 onClick 只能用在客户端组件里：这个组件用了互动功能，却没标 'use client'。在文件第一行加上，注意必须在所有 import 之前。"use client" 的组件导出 metadata：页面被整个标成了客户端组件。去掉页面的 'use client'，把需要互动的部分拆成单独的组件。localStorage is not defined 或 window is not defined：在组件渲染时直接用了浏览器专属功能。客户端组件也会在服务器上先渲染，改用 useSyncExternalStore（上午第 6 节），或者只在点击事件的处理函数里使用。localStorage、Math.random()、当前时间。浏览器装的翻译或广告拦截插件也会改页面导致这个报错，可以用无痕窗口排除。测试小游戏为什么必须是客户端组件？
测试小游戏要用 useState 记住当前第几题和已经选的答案，要用 onClick 响应每一次选择，并立刻更新界面，这些都只能在浏览器里完成。服务端组件只在服务器上运行一次，把结果发出去就结束了，没有状态也不能响应点击，所以测试小游戏必须标 'use client'。而它外面的页面只负责标题和说明，可以留在服务端。
如果在 app/page.tsx 顶部写 'use client'，功能上看起来还能用，为什么不推荐？
整个首页和它导入的所有组件都会被打包送进浏览器，页面变重、打开变慢；页面不能再写成 async，以后没法在页面里直接查数据库；也不能导出 metadata。应该让页面留在服务端，只把筛选这类需要互动的部分拆成小的客户端组件。
首页把 looks 作为 props 传给 LookFilter，这些数据访客能看到吗？这对以后有什么提醒？
能看到。传给客户端组件的数据会随页面发到浏览器，用开发者工具就能翻出来。所以以后从数据库查到数据再传给客户端组件时，只传界面需要的字段，比如标题、描述、世界名，不要把整条数据库记录，尤其是不该公开的字段，原样传过去。
practice 数据库。CREATE TABLE、INSERT、SELECT、WHERE、ORDER BY、UPDATE、DELETE，并看懂每条语句的结果。UPDATE 和 DELETE 不写 WHERE 的后果，养成“先 SELECT 看一眼再改”的习惯。到昨天为止，官网的穿搭、世界介绍都写在 lib/data/*.ts 里。这样做有两个问题。第一，每加一套穿搭都要改代码、提交、重新部署，你拍完视频想更新一下官网，得先打开 VS Code。第二，也是更根本的：DAY 43 起粉丝要在官网上给你提问，粉丝的问题是访客在网页上写的，不可能提前写进你的代码里。
数据库就是解决这个问题的：一个专门存数据、随时可以读写的地方，而且和代码分开。代码负责“怎么显示”，数据库负责“显示什么”。以后你在后台新增一套穿搭，数据写进数据库，官网下一次打开就能看到，代码一行都不用动。
你可能会问：DAY 22 我把平台链接放进过 data.json，为什么不继续用 JSON 文件存？JSON 文件适合“只读、偶尔手动改”的数据。一旦要让很多访客同时往里写，问题就来了：两个粉丝同一秒提交问题，后写的可能把先写的覆盖掉；文件越来越大，想找出“街头世界里最新的三条”就得把整个文件读进来一条条翻；而且部署到 Vercel 后，网站的文件是只读的，根本写不进去。数据库天生就是为同时读写、快速查找、不丢数据设计的。
可以把数据库想成一个仓库。仓库里有好几个货架，每个货架只放一类东西：一个放“世界”，一个放“穿搭”，一个放“粉丝提问”。每个货架上的格子排得整整齐齐，每一格放一件东西，每件东西都贴着同样格式的标签。
把仓库的比喻换成术语：货架叫表（table），一件东西叫一行（row），标签上的每一项叫一列（column）。一张存穿搭的 looks 表看起来像这样：
| id | title | world | published | created_at |
|---|---|---|---|---|
| 1 | 深灰马甲配白衬衫 | gentleman | true | 2026-09-01 20:00 |
| 3 | Baggy 裤配 Vans | street | true | 2026-09-05 16:00 |
| 5 | 红色泰拳短裤 | thai | true | 2026-09-12 08:00 |
它很像 Excel，但有一个关键区别：每一列的类型是事先规定好的。published 列只能放真或假，你往里写“是的”会直接被拒绝。这种严格正是数据库可靠的原因。今天会用到这几种类型：
TEXT：文字，长短不限。INTEGER：整数。SERIAL：自动递增的整数，每插入一行自动加 1，专门用来当编号。BOOLEAN：真（true）或假（false）。TIMESTAMP：日期加时间。列上还可以加规则，叫约束：NOT NULL 表示这一列必须有值；DEFAULT 表示没填时用什么默认值；UNIQUE 表示这一列的值不能重复；PRIMARY KEY（主键）表示这一列是每一行的身份证号，既不能为空也不能重复，数据库靠它精确找到某一行。几乎每张表都有一个叫 id 的主键。
还有一个特殊的值 NULL，意思是“这里没有值”，不是空字符串，也不是 0。比如粉丝提问时没留昵称，昵称就是 NULL。
数据库是一类软件，市面上有好几种，我们用的是 PostgreSQL（常简称 Postgres）。它免费、开源、稳定，是现在网站开发里最常用的数据库之一。和数据库“说话”的语言叫 SQL，几乎所有这一类数据库都用它，今天学的写法换到别的数据库大多也通用。
数据库软件要装在一台一直开着的电脑上。自己买服务器、装软件、做备份很麻烦，所以我们用 Neon：它在云上帮你运行 PostgreSQL，你只管用。免费套餐对个人官网绰绰有余。Neon 有个特点叫“闲置自动休眠”：几分钟没人访问，它会把计算资源停掉省钱，下一次访问时再自动启动，所以休眠后的第一次查询可能会慢一点点，这是正常的。
Neon 里有三层概念：
dongge-web。production 的分支，我们先只用它。neondb。区域选新加坡。区域就是数据库放在哪个城市的机房，离你的观众和网站服务器越近，每次查询越快。
今天我们会在同一个分支里再建一个叫 practice 的数据库专门练习，把 neondb 留干净，DAY 42 让 Prisma 在里面建正式的表。这样练习时随便建、随便删，都不会影响正式数据。
SQL 语句读起来很像英文句子。建一张表：
CREATE TABLE worlds (
id SERIAL PRIMARY KEY,
slug TEXT NOT NULL UNIQUE,
name TEXT NOT NULL,
feeling TEXT NOT NULL
);逐行看：CREATE TABLE worlds 创建一张叫 worlds 的表。括号里每一行定义一列，格式是“列名 类型 约束”。id 是自动递增的编号，也是主键；slug 是 gentleman 这样的英文短名，不能为空也不能重复；name 和 feeling 是中文名和给人的感受。列与列之间用逗号隔开，最后一列后面没有逗号。整条语句以分号结尾。
往表里放数据用 INSERT：
INSERT INTO worlds (slug, name, feeling) VALUES
('gentleman', '绅士', '安全感'),
('street', '街头', '心动'),
('thai', '泰风', '被保护感');第一个括号列出要填的列，VALUES 后面每个括号是一行数据，值的顺序和前面列的顺序一一对应。没写 id，因为它是 SERIAL，数据库会自动填 1、2、3。文字要用单引号括起来，这点和 JavaScript 不同：SQL 里双引号有别的用途（用来括列名或表名），写文字一律用单引号。
SQL 关键字写大写还是小写都可以，大写只是习惯，让人一眼分清哪些是关键字、哪些是你起的名字。以 -- 开头的是注释，数据库会忽略它。
查询是你以后用得最多的。最基本的形式：
SELECT title, world FROM looks;意思是“从 looks 表里取出 title 和 world 两列”。想要所有列，写 SELECT *，星号代表全部。
加上 WHERE 就是筛选，只要满足条件的行：
SELECT * FROM looks
WHERE world = 'street' AND published = true
ORDER BY created_at DESC
LIMIT 3;逐行看：取 looks 表的所有列；只要世界是 street、并且已经发布的行；按创建时间排序，DESC 是从大到小，时间越大越新，所以就是从新到旧，不写或写 ASC 是从小到大；最后只要前 3 行。一条 SQL 可以写成多行，数据库看的是分号，换行只是为了好读。
WHERE 里常用的写法：
= 等于，<> 不等于，>、< 比大小。注意等于是一个等号，不是 JavaScript 的 ===。AND 两个条件都要满足，OR 满足一个就行，和 JavaScript 的 &&、|| 一个意思。world IN ('gentleman', 'thai')：是这几个中的一个。title LIKE '%衬衫%'：模糊匹配，% 代表任意几个字，这句就是“标题里包含衬衫”。nickname IS NULL：没有值。判断 NULL 必须用 IS NULL 或 IS NOT NULL，写 = NULL 永远查不到任何行，因为 NULL 表示“未知”，未知和任何东西比较的结果都是未知。数一数有几行用 COUNT(*)：SELECT COUNT(*) FROM looks WHERE world = 'thai'; 返回的是一个数字，而不是一行行数据。
改数据用 UPDATE，删数据用 DELETE：
UPDATE looks SET published = true WHERE id = 2;
DELETE FROM looks WHERE id = 7;第一句：把 looks 表里 id 为 2 的那一行的 published 改成 true。SET 后面可以用逗号隔开同时改好几列。第二句：删掉 id 为 7 的那一行。
这两条语句最危险的地方在于 WHERE。如果忘了写 WHERE，UPDATE looks SET published = true; 会把所有穿搭都改成已发布，DELETE FROM looks; 会把整张表清空。数据库不会弹窗问你“确定吗”，也没有撤销按钮。Neon 有恢复历史数据的功能，但那是最后的保险，不能当作日常手段。
所以养成一个习惯：改和删之前，先把同样的 WHERE 放进 SELECT 里跑一遍，确认查出来的正是你想改的那几行，再把 SELECT * 换成 UPDATE ... SET ... 或 DELETE。尽量用 id 来定位，因为 id 是唯一的，用标题定位万一有两行同名就会一起被改。
今天在 practice 库里练，改坏了大不了删表重建。等到正式数据库里有了你真实的穿搭和粉丝提问，这个习惯会救你。
SQL 看起来是一门新语言，其实你已经会它的大部分思路了。DAY 16 你学过数组的 filter、map、sort，SQL 做的是同样的事，只是对象从“内存里的数组”换成了“数据库里的表”：
| SQL | JavaScript 里的近亲 |
|---|---|
WHERE world = 'street' | looks.filter((look) => look.world === 'street') |
SELECT title, world | looks.map((look) => ({ title: look.title, world: look.world })) |
ORDER BY created_at DESC | looks.sort(...)，按时间从大到小 |
LIMIT 3 | looks.slice(0, 3) |
COUNT(*) | looks.length |
有一个重要的区别：JavaScript 里你要一步步写“怎么做”，先筛选再排序再截取；SQL 里你只描述“要什么”，比如“街头的、按时间倒序、前三条”，至于先做哪一步、怎么做最快，交给数据库自己决定。这种写法叫“声明式”。数据库在这方面非常擅长，表里有一百万行时，它依然能很快找出你要的三行，这是在代码里用数组做不到的。
还有一点要记住：SQL 语句的书写顺序是固定的，SELECT ... FROM ... WHERE ... ORDER BY ... LIMIT ...，顺序写乱就会报语法错。刚开始可以把这一行抄在便利贴上贴在屏幕边。
DAY 42 起你会用 Prisma 在 TypeScript 里操作数据库，写起来更像你熟悉的对象和函数，Prisma 会把它翻译成今天这样的 SQL。所以今天的 SQL 不会白学：当 Prisma 的查询结果不对，你要能看懂它背后的 SQL；DAY 61 做数据看板时，还要直接写 SQL 做统计。
明天我们会让三张表之间建立关系：现在 looks 表里的 world 列存的是 'street' 这样的文字，万一有人写成 'Street' 或 'streat'，数据库并不会拦着。明天会用 worlds 表的 id 把穿搭和世界真正连起来，让数据库替你把关。
注册 Neon
打开 neon.com，点注册，推荐用 GitHub 账号登录，少记一个密码。登录用的密码由你自己在弹出的 GitHub 页面里输入。注册时选免费套餐（Free），不需要绑定银行卡。如果页面提示升级付费套餐，先不要点，免费额度足够你用到课程结束。
新建项目，选新加坡
在控制台点 New Project：
dongge-webAWS Asia Pacific (Singapore)点 Create project。界面文字可能会有变化，意思对上就行。
dongge-web 和分支 production。建一个练习用的数据库
左侧边栏找到 Postgres database 下的 Databases，点 Add database，名字填 practice，owner 选默认的那个角色，点 Create。
neondb 和 practice 两个。打开 SQL 编辑器，切到 practice
左侧边栏点 SQL Editor。编辑器上方有两个下拉框，分支选 production，数据库一定要选 practice。第一次打开时编辑器里可能有一段示例 SQL，全部删掉，输入：
SELECT version();点 Run。
PostgreSQL 开头的版本信息。练习 1–6：建表和插入
每一题先自己写，写完运行，看结果对不对，再展开参考答案对照。编辑器里一次可以写多条语句，每条都会有自己的结果标签页；但刚开始建议一题一题跑，出错时好找原因。
练习 1：建 worlds 表：id（自动编号、主键）、slug（文字、必填、不重复）、name（文字、必填）、feeling（文字、必填）。
CREATE TABLE worlds (
id SERIAL PRIMARY KEY,
slug TEXT NOT NULL UNIQUE,
name TEXT NOT NULL,
feeling TEXT NOT NULL
);练习 2：一条语句插入三个世界：绅士 / 安全感，街头 / 心动，泰风 / 被保护感。
INSERT INTO worlds (slug, name, feeling) VALUES
('gentleman', '绅士', '安全感'),
('street', '街头', '心动'),
('thai', '泰风', '被保护感');练习 3：查出 worlds 表的全部数据。
SELECT * FROM worlds;id 列自动出现了 1、2、3。
练习 4：只查中文名和感受两列。
SELECT name, feeling FROM worlds;练习 5：建 looks 表：id（自动编号、主键）、title（文字、必填）、description（文字、必填）、world（文字、必填，放 slug）、published（真假、必填、默认 false）、created_at（时间、必填、默认当前时间）。
CREATE TABLE looks (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
description TEXT NOT NULL,
world TEXT NOT NULL,
published BOOLEAN NOT NULL DEFAULT false,
created_at TIMESTAMP NOT NULL DEFAULT now()
);now() 是 PostgreSQL 的函数，返回当前时间。
练习 6：插入 6 套穿搭。为了后面练排序，这次手动指定 created_at。可以直接复制下面的语句，但要看懂每一列对应哪个值。
INSERT INTO looks (title, description, world, published, created_at) VALUES
('深灰马甲配白衬衫', '打斯诺克那天穿的，袖子挽到小臂。', 'gentleman', true, '2026-09-01 20:00'),
('棕色皮鞋和西裤', '鞋头擦过一遍，站在球台边不抢戏。', 'gentleman', false, '2026-09-03 19:30'),
('Baggy 裤配 Vans', '骑 BMX 不卡腿，摔了也不心疼。', 'street', true, '2026-09-05 16:00'),
('Oversize 白 T', '滑板公园的标准装，风一吹就鼓起来。', 'street', true, '2026-09-10 17:20'),
('红色泰拳短裤', '训练完绑带还没拆。', 'thai', true, '2026-09-12 08:00'),
('泰式印花衬衫', '打完拳去吃泰餐时换上的那件。', 'thai', false, '2026-09-15 21:10');练习 7–15：查询
练习 7：查出所有穿搭的标题和世界。
SELECT title, world FROM looks;练习 8：只看街头的穿搭。
SELECT * FROM looks WHERE world = 'street';练习 9：只看已发布的穿搭。
SELECT * FROM looks WHERE published = true;练习 10：看街头里已发布的。
SELECT * FROM looks WHERE world = 'street' AND published = true;练习 11：看绅士和泰风两个世界的穿搭（用 IN）。
SELECT * FROM looks WHERE world IN ('gentleman', 'thai');也可以写成 WHERE world = 'gentleman' OR world = 'thai'，结果一样。
练习 12：所有穿搭按时间从新到旧排。
SELECT * FROM looks ORDER BY created_at DESC;练习 13：只要最新的 3 套。
SELECT * FROM looks ORDER BY created_at DESC LIMIT 3;练习 14：找出标题里带“衬衫”的穿搭。
SELECT * FROM looks WHERE title LIKE '%衬衫%';应该查出“深灰马甲配白衬衫”和“泰式印花衬衫”两行。
练习 15：数一数：一共有几套穿搭？泰风里已发布的有几套？
SELECT COUNT(*) FROM looks;
SELECT COUNT(*) FROM looks WHERE world = 'thai' AND published = true;分别是 6 和 1。
练习 16–20：修改、删除和 NULL
练习 16：把“棕色皮鞋和西裤”改成已发布。按“先看再改”的习惯：先查出它的 id，再用 id 改，改完再查一次确认。
SELECT id, title, published FROM looks WHERE title = '棕色皮鞋和西裤';
UPDATE looks SET published = true WHERE id = 2;
SELECT id, title, published FROM looks WHERE id = 2;如果你查出来的 id 不是 2，就用你查到的那个数字。
练习 17：一条语句同时修改“泰式印花衬衫”的描述和发布状态。描述改成：配一条黑色短裤，打完拳直接去夜市。
UPDATE looks
SET description = '配一条黑色短裤，打完拳直接去夜市。', published = true
WHERE id = 6;练习 18：插入一条标题为“测试用”的街头穿搭，查出它的 id，再把它删掉，最后确认它不在了。
INSERT INTO looks (title, description, world) VALUES ('测试用', '马上删掉', 'street');
SELECT id, title FROM looks WHERE title = '测试用';
DELETE FROM looks WHERE id = 7;
SELECT * FROM looks WHERE title = '测试用';插入时没写 published 和 created_at，数据库自动用了默认值。最后一句应该查不到任何行。
练习 19：建 questions 表（粉丝提问箱）：id、content（必填）、nickname（可以为空）、status（必填，默认 PENDING）、answer（可以为空）、created_at（默认当前时间）。插入两条提问，一条留昵称“小鹿”，一条不留昵称，然后查出没留昵称的提问。
CREATE TABLE questions (
id SERIAL PRIMARY KEY,
content TEXT NOT NULL,
nickname TEXT,
status TEXT NOT NULL DEFAULT 'PENDING',
answer TEXT,
created_at TIMESTAMP NOT NULL DEFAULT now()
);
INSERT INTO questions (content, nickname) VALUES ('打斯诺克前你会先做什么？', '小鹿');
INSERT INTO questions (content) VALUES ('滑板摔了还会继续吗？');
SELECT * FROM questions WHERE nickname IS NULL;没写 NOT NULL 的列就允许为空。试一下把最后一句改成 WHERE nickname = NULL，会发现一行都查不到。
练习 20：挑战题：每个世界各有几套穿搭？提示：用 GROUP BY world 把行按世界分组，再对每组 COUNT(*)。
SELECT world, COUNT(*) FROM looks GROUP BY world;结果是三行，每个世界一行，后面跟着数量。明天学表关系时还会用到分组。
保存练习，看看表格视图
把你觉得最有用的几条 SQL 点 Save 存起来，以后在左侧的 Saved 列表里能找到；跑过的语句也会自动出现在 History 里。然后在左侧边栏打开 Tables，选 practice 数据库，能像看表格一样看到三张表里的数据。
worlds、looks、questions 三张表，looks 有 6 行。认识连接字符串，但先别复制
点项目页面上的 Connect 按钮，会弹出一个窗口，里面有一串以 postgresql:// 开头的连接字符串。它包含数据库的用户名和密码，谁拿到它谁就能读写你的数据库。今天只看一眼，关掉窗口。DAY 42 我们会把它放进 .env 文件，而且永远不提交到 Git、不贴到聊天里，包括发给 Claude。
让 Claude 再出几道题
用 claude 部分的第一条提示词，让 Claude 根据你的表出 5 道新题。自己在 SQL 编辑器里写完、跑通，再把答案发给它批改。
relation "looks" does not exist：表不存在。最常见的原因是编辑器上方的数据库选成了 neondb，而表建在 practice 里；或者建表那句根本没成功运行。先检查下拉框。column "street" does not exist：文字用了双引号，写成了 WHERE world = "street"。SQL 里双引号表示列名，文字要用单引号 'street'。relation "worlds" already exists：同一张表建了两次。表已经在了，不用再建；想重来就先 DROP TABLE worlds; 删掉整张表，再重新建。DROP TABLE 会连数据一起删，只在练习库里这么做。syntax error at or near ...：语法错，看报错里提到的位置附近。常见原因：最后一列后面多了逗号、中文逗号或中文引号混进了语句、少了分号导致两条语句连在一起。写一条 SQL：查出所有“街头”世界的 look，按时间从新到旧排。
SELECT * FROM looks
WHERE world = 'street'
ORDER BY created_at DESC;WHERE 负责只留下街头，ORDER BY created_at DESC 按时间从大到小排，也就是从新到旧。如果只想看已发布的，再加 AND published = true。
有人运行了 UPDATE looks SET published = true;，会发生什么？你会用什么习惯避免这种事？
没有 WHERE，所有穿搭都会被改成已发布，数据库不会提示，也不能撤销。避免的习惯是：改和删之前先用同样的 WHERE 写一条 SELECT，确认查出来的正好是要改的行，再换成 UPDATE；并且尽量用唯一的 id 定位。
为什么 SELECT * FROM questions WHERE nickname = NULL; 一行都查不到？应该怎么写？
NULL 表示“没有值、未知”，未知和任何值比较，结果都是未知，不算“真”，所以没有行满足条件。判断空值要写 WHERE nickname IS NULL，判断不为空写 IS NOT NULL。
looks 连到 worlds，并亲眼看到数据库拒绝指向不存在世界的数据。JOIN 和 LEFT JOIN，把穿搭和它所属世界的中文名一起查出来，并按世界分组统计。world_id 建索引。worlds、looks、questions 三张表的设计和关系图，并让 Claude 审查。昨天 looks 表里有一列 world，存的是 'street' 这样的文字。它能用，但藏着三个隐患：
world = 'streat'，数据库照单全收，这套穿搭从此在哪个世界里都找不到。worlds 表里，但 looks 表只写了 slug，两张表之间的联系全靠你自己记着“这两个 street 是同一个意思”。thai 改成 muaythai，得去 looks 表里把每一行都改一遍，漏一行就出错。解决办法是：looks 表不再抄写世界的名字，而是记住世界的编号。就像快递单上不写收件人的全部资料，只写一个会员号，要详细信息时拿会员号去会员表里查。
昨天你已经认识了主键：每张表的 id 列，是每一行的身份证号，不重复、不为空。今天的新概念是外键：一张表里的某一列，专门用来存另一张表的主键。
CREATE TABLE looks (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
description TEXT NOT NULL,
published BOOLEAN NOT NULL DEFAULT false,
created_at TIMESTAMP NOT NULL DEFAULT now(),
world_id INTEGER NOT NULL REFERENCES worlds(id)
);关键是最后一行：world_id 是整数，必填，REFERENCES worlds(id) 表示“这一列的值必须是 worlds 表里真实存在的某个 id”。这一句就是外键约束。有了它，数据库会替你把关：
world_id = 99 的穿搭，而 worlds 表里没有 99，数据库直接报错拒绝。拼错的问题从根上消失了。第二条是默认行为。也可以在外键后面加 ON DELETE CASCADE，意思是“删世界时连带删掉它的所有穿搭”。这很方便也很危险，对你的官网来说，默认的“拒绝删除”更安全：想删世界，先把穿搭处理掉，逼你想清楚再动手。
命名上有个惯例：外键列叫“对方表名的单数 + _id”，所以叫 world_id。一看名字就知道它指向哪张表。
注意 world_id 后面还有 NOT NULL。外键本身允许为空，为空表示“不属于任何一方”。要不要加 NOT NULL，取决于业务：你的每套穿搭都必须属于某个世界，没有“不属于任何世界”的穿搭，所以加上。如果哪天你想发一套“日常”穿搭、不归三个世界中的任何一个，那时才需要考虑让它可以为空。约束写得越贴近真实规则，数据库就越能替你挡住错误。
表和表之间最常见的关系是一对多：一个世界有很多套穿搭，而一套穿搭只属于一个世界。
外键放在哪张表？答案是放在“多”的那一边，也就是 looks。想一想反过来会怎样：如果在 worlds 表里加一列记录它有哪些穿搭，街头有 2 套就要存两个 id，以后有 30 套就要存 30 个，一个格子里塞一串数字，既没法约束，也没法查询。而每套穿搭只属于一个世界，在 looks 里放一个 world_id，每个格子只放一个数字，干干净净。
记一个口诀：谁“属于”谁，外键就放在谁身上。穿搭属于世界，所以穿搭身上带着世界的编号。就像每个学生的学籍卡上写着班级号，而不是班级卡上列出所有学生。
另外两种关系先认识一下名字：一对一，比如一个用户对应一份个人资料；多对多，比如一套穿搭可以打好几个标签，一个标签也可以用在好几套穿搭上，这需要第三张“中间表”来记录配对。你的官网暂时只需要一对多。DAY 46 接入 Better Auth 时，它自带的用户表和会话表之间也是一对多：一个用户可以在好几台设备上登录。
数据分到两张表以后，想显示“穿搭标题 + 世界中文名”，就要把两张表拼在一起查，这叫 JOIN（连接）：
SELECT looks.title, worlds.name
FROM looks
JOIN worlds ON looks.world_id = worlds.id;逐行看：取 looks 表的 title 和 worlds 表的 name。两张表都有 id 这样的同名列，所以要写成“表名.列名”说清楚是哪张表的。FROM looks JOIN worlds 表示把两张表拼起来，ON 后面是拼接的规则：穿搭的 world_id 等于世界的 id 的两行，拼成结果里的一行。
数据库做的事，就像你手里拿着一叠穿搭卡片，每张卡片上写着世界编号，你照着编号去世界表里找到对应的那一行，把中文名抄到卡片旁边。
JOIN 之后照样可以用昨天学的 WHERE、ORDER BY：
SELECT looks.title, looks.created_at
FROM looks
JOIN worlds ON looks.world_id = worlds.id
WHERE worlds.slug = 'street'
ORDER BY looks.created_at DESC;这就是昨天验收题的新版本：条件从 looks.world = 'street' 变成了 worlds.slug = 'street'。
只写 JOIN 时，默认是 INNER JOIN（内连接）：只保留两边都能配上对的行。如果有一个世界还没有任何穿搭，它不会出现在结果里。想让“没有穿搭的世界”也出现，用 LEFT JOIN：左边那张表（写在 FROM 后面的）每一行都保留，右边配不上的地方填 NULL。
SELECT worlds.name, COUNT(looks.id) AS look_count
FROM worlds
LEFT JOIN looks ON looks.world_id = worlds.id
GROUP BY worlds.name;这句统计每个世界有几套穿搭。GROUP BY worlds.name 把结果按世界分组，COUNT(looks.id) 数每组里有几个穿搭 id，NULL 不算，所以没有穿搭的世界会显示 0。AS look_count 给这一列起个好读的名字。以后在后台做“每个世界有多少内容”的统计，就是这个写法。
一本 500 页的书，想找“泰拳”出现在哪几页，没有目录只能从第一页翻到最后一页；有了书后面的索引，直接翻到 T 开头那栏就找到了。数据库的索引是同一个东西：为某一列额外建一份排好序的“目录”，按这一列查找时不用把整张表从头扫到尾。
PostgreSQL 会自动给主键和 UNIQUE 的列建索引，所以按 id 查、按 slug 查本来就快。但外键列不会自动建索引。你的官网最常见的查询是“某个世界的所有穿搭”，也就是按 world_id 查，所以值得给它建一个：
CREATE INDEX looks_world_id_idx ON looks (world_id);索引名随你起，习惯写成“表名_列名_idx”。
索引不是越多越好。每插入或修改一行，数据库都要顺便更新所有相关的目录，索引越多写入越慢，也更占空间。所以只给经常用来查找、筛选、排序的列建。想知道一条查询到底有没有用上索引，可以在它前面加 EXPLAIN 运行，数据库会告诉你它打算怎么查，而不真正执行；Neon 的 SQL 编辑器里也有一个 Explain 按钮做同样的事。数据很少时，数据库常常觉得“直接扫一遍更快”而不用索引，这是正常的。你的数据量现在只有几十行，有没有索引感觉不出差别；但养成“外键列加索引”的习惯，等穿搭多到几千条时就不用回头补。
把今天学的放在一起，官网正式用的三张表设计如下。image_url 先留着，DAY 49 上传图片时用：
CREATE TABLE worlds (
id SERIAL PRIMARY KEY,
slug TEXT NOT NULL UNIQUE,
name TEXT NOT NULL,
feeling TEXT NOT NULL
);
CREATE TABLE looks (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
description TEXT NOT NULL,
image_url TEXT,
published BOOLEAN NOT NULL DEFAULT false,
created_at TIMESTAMP NOT NULL DEFAULT now(),
world_id INTEGER NOT NULL REFERENCES worlds(id)
);
CREATE INDEX looks_world_id_idx ON looks (world_id);
CREATE TABLE questions (
id SERIAL PRIMARY KEY,
content TEXT NOT NULL,
nickname TEXT,
status TEXT NOT NULL DEFAULT 'PENDING'
CHECK (status IN ('PENDING', 'APPROVED', 'HIDDEN')),
answer TEXT,
created_at TIMESTAMP NOT NULL DEFAULT now()
);几处设计决定说明一下：
published 默认 false：新建的穿搭先是草稿，你确认后才发布，前台只显示已发布的。questions.status 只能是三个值之一：待审核、已通过、已隐藏。CHECK 是另一种约束，让数据库拒绝这三个以外的值。粉丝提交的问题默认待审核，DAY 50 你在后台审核后才会在前台显示。nickname 和 answer 可以为空：粉丝可以匿名，你也不一定每条都回答。questions 不和别的表关联：粉丝不需要注册，问题也不属于某个世界。不是每张表都必须有外键，有真实的“属于”关系才建。created_at），这是 PostgreSQL 圈子里最常见的写法。画成关系图是这样：
worlds looks
+----------------+ +----------------------+
| id PK |--1----n-->| world_id FK |
| slug UNIQUE | | id PK |
| name | | title |
| feeling | | description |
+----------------+ | image_url 可为空 |
| published |
| created_at |
+----------------------+
questions（独立的表，不和其他表关联）
+----------------------+
| id PK |
| content |
| nickname 可为空 |
| status PENDING / APPROVED / HIDDEN |
| answer 可为空 |
| created_at |
+----------------------+判断一份表设计好不好，最实用的办法是：把官网上每一个要显示数据的地方列出来，看看能不能用一条不太复杂的 SQL 查出来。查不出来，或者要绕很大的弯，说明设计有问题。拿这三张表试一试：
| 页面上的需求 | 查询思路 |
|---|---|
| 首页：最新发布的几套穿搭，带世界中文名 | looks JOIN worlds，WHERE published = true，按 created_at 倒序，LIMIT |
| 世界页：街头的所有已发布穿搭 | 同上，再加 worlds.slug = 'street' |
| 提问箱前台：只显示通过审核的提问和回答 | questions，WHERE status = 'APPROVED'，按时间倒序 |
| 后台：待审核的提问，先来的排前面 | questions，WHERE status = 'PENDING'，按时间正序 |
| 后台：每个世界有几套穿搭 | worlds LEFT JOIN looks，GROUP BY |
每一条都能用今天和昨天学的语法写出来，说明这份设计够用。这个“先想页面要查什么，再设计表”的顺序很重要：新手常犯的错是先凭感觉建表，等写页面时才发现要的数据拿不到，只好回头改表。以后你给官网加新功能，比如 DAY 59 存 AI 文案草稿、DAY 60 记录按钮点击，都先做这一步：列出要显示什么、要统计什么，再决定表长什么样。
还有一个值得留意的地方：表里存的是“事实”，不存“能算出来的东西”。比如“街头有几套穿搭”不需要在 worlds 表里加一列 look_count，因为随时可以用 COUNT 算出来；如果存了，每次增删穿搭都得记得同步更新它，忘一次数字就错了。
这份设计今天只写在文档里，不要在 neondb 里运行。明天你会用 Prisma 把它写成代码，由 Prisma 在 neondb 里建出一模一样的表。手写 SQL 建表和用工具建表，结果是一样的，但用工具的好处是每一次改动都有记录，这是明天的主题。
先在纸上画
不看上午第 6 节，拿一张纸画出你认为官网需要的三张表：每张表有哪些列、哪一列是主键、哪一列是外键、箭头从哪指向哪。画完再对照课件，把不一样的地方标出来，想想谁的更合理。你的想法有道理的，可以保留，下午让 Claude 一起评估。
在 practice 库里重建 looks 表
打开 Neon 的 SQL 编辑器，数据库选 practice。先看看三个世界的 id：
SELECT id, slug FROM worlds;记下 gentleman、street、thai 各自的 id（一般是 1、2、3）。然后删掉昨天的 looks 表，按新设计重建：
DROP TABLE looks;
CREATE TABLE looks (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
description TEXT NOT NULL,
image_url TEXT,
published BOOLEAN NOT NULL DEFAULT false,
created_at TIMESTAMP NOT NULL DEFAULT now(),
world_id INTEGER NOT NULL REFERENCES worlds(id)
);插入 6 套穿搭，这次最后一列填世界的 id。如果你查到的 id 不是 1、2、3，替换成你的：
INSERT INTO looks (title, description, published, created_at, world_id) VALUES
('深灰马甲配白衬衫', '打斯诺克那天穿的，袖子挽到小臂。', true, '2026-09-01 20:00', 1),
('棕色皮鞋和西裤', '鞋头擦过一遍，站在球台边不抢戏。', true, '2026-09-03 19:30', 1),
('Baggy 裤配 Vans', '骑 BMX 不卡腿，摔了也不心疼。', true, '2026-09-05 16:00', 2),
('Oversize 白 T', '滑板公园的标准装，风一吹就鼓起来。', true, '2026-09-10 17:20', 2),
('红色泰拳短裤', '训练完绑带还没拆。', true, '2026-09-12 08:00', 3),
('泰式印花衬衫', '配一条黑色短裤，打完拳直接去夜市。', false, '2026-09-15 21:10', 3);SELECT * FROM looks; 显示 6 行，最后一列是 1、1、2、2、3、3。故意违反外键，看数据库怎么拦
INSERT INTO looks (title, description, world_id) VALUES ('不存在的世界', '测试外键', 99);violates foreign key constraint，表里没有多出这一行。再试着删掉泰风：
DELETE FROM worlds WHERE slug = 'thai';SELECT * FROM worlds; 泰风还在。用 JOIN 查出穿搭和世界名
先自己写：查出每套穿搭的标题和它所属世界的中文名。写完对照上午第 4 节。然后写验收题的 JOIN 版本：只要街头的穿搭，按时间从新到旧排。
体会 INNER JOIN 和 LEFT JOIN 的区别
临时加一个还没有穿搭的世界：
INSERT INTO worlds (slug, name, feeling) VALUES ('test', '测试世界', '无');分别运行下面两条，比较结果：
SELECT worlds.name, looks.title
FROM worlds
JOIN looks ON looks.world_id = worlds.id;
SELECT worlds.name, looks.title
FROM worlds
LEFT JOIN looks ON looks.world_id = worlds.id;再运行上午第 4 节的分组统计，“测试世界”应该显示 0。看完把它删掉：DELETE FROM worlds WHERE slug = 'test';，这次能删成功，想想为什么。
建索引，并确认它存在
CREATE INDEX looks_world_id_idx ON looks (world_id);
SELECT indexname FROM pg_indexes WHERE tablename = 'looks';pg_indexes 是 PostgreSQL 自带的一张“系统表”，记录着所有索引。
looks_pkey（主键自动建的）和你刚建的 looks_world_id_idx。把设计写成文档
在 ~/code/dongge-web 里新建 docs/database.md，写下三张表的设计：每一列的名字、类型、是否必填、默认值、说明，外键指向哪里，再把关系图画进去（可以用上午的文字图，也可以按你纸上画的改）。最后写三句话说明你的设计决定，比如“为什么 questions 没有外键”。
cd ~/code/dongge-web
mkdir -p docs
code docs/database.mdcode 命令会用 VS Code 打开这个文件。如果提示找不到 code 命令，直接在 VS Code 里新建文件也一样。
让 Claude 审查你的设计（Plan 模式）
切到 Plan 模式，发送 claude 部分的第一条提示词。它可能会提出一些建议，比如给 questions.status 加索引、给 looks 加更新时间。对每条建议问自己：“我的官网现在真的需要吗？”需要的记下来，明天写 Prisma 时加上；暂时不需要的，在文档里写一句“以后再考虑”。你是做决定的人，Claude 只是提建议。
提交设计文档
git add docs/database.md
git commit -m "官网数据库设计：worlds、looks、questions"
git pushDROP TABLE looks 报错说有别的对象依赖它：如果你昨天之后又建了引用 looks 的表，就会这样。练习库里可以用 DROP TABLE looks CASCADE; 连带删除依赖；正式库里千万别随手用 CASCADE。ON 条件写错了，比如写成了 looks.id = worlds.id，或者忘了写 ON。检查拼接规则是不是“外键 = 对方主键”。column reference "id" is ambiguous：两张表都有 id 列，数据库不知道你指哪一个。写成 looks.id 或 worlds.id。worlds 表里的对不上，比如删过再插入导致 id 变成了 4、5、6。先 SELECT id, slug FROM worlds; 看清楚真实的 id。must appear in the GROUP BY clause：SELECT 里出现了没有分组、也没有用 COUNT 这类函数包起来的列。SELECT 里的普通列都要写进 GROUP BY。looks 和 worlds 是什么关系？外键应该放在哪张表？
一对多：一个世界有多套穿搭，一套穿搭只属于一个世界。外键放在“多”的那一边，也就是 looks 表，列名 world_id，指向 worlds.id。放在 looks 里每行只需要存一个数字；如果放在 worlds 里，一个格子就要塞下一串穿搭 id，既不能约束也不好查询。
用你今天的数据举例，说说 JOIN 和 LEFT JOIN 的区别。
JOIN（内连接）只保留两边能配上的行，所以没有穿搭的“测试世界”不会出现。LEFT JOIN 保留左边表（FROM 后面的 worlds）的每一行，右边配不上时填 NULL，所以“测试世界”会出现，穿搭标题是 NULL。统计“每个世界有几套穿搭、包括 0 套的”要用 LEFT JOIN。
索引能让查询变快，为什么不干脆给每一列都建索引？
索引是额外维护的一份目录，每次插入、修改、删除数据，数据库都要同步更新所有相关索引，索引越多写入越慢，也越占存储空间。所以只给经常用来查找、筛选、排序的列建，比如外键 world_id；很少用来查的列不需要。
dongge-web 里装好 Prisma 7，配好 DATABASE_URL，把昨天的三张表写成 schema.prisma。prisma migrate dev 在 Neon 里建出表，并读懂自动生成的迁移 SQL。前两天你在 Neon 的编辑器里手写 SQL。网站当然也可以直接把 SQL 字符串发给数据库，但会遇到几个麻烦：SQL 写在字符串里，拼错一个列名，编辑器不会提示，要等运行时才报错；查出来的数据在 TypeScript 眼里是“不知道什么类型”，look.titel 写错了也发现不了；表结构改了，哪些代码受影响全靠记忆。
Prisma 是一个 ORM（对象关系映射）工具，站在你的代码和数据库中间当翻译。你用 TypeScript 写 prisma.look.findMany({ where: { published: true } })，它翻译成 SQL 发给数据库，再把结果翻译回带类型的对象。编辑器能自动补全表名和列名，写错了立刻标红。
Prisma 由三部分组成，今天全部会用到：
prisma/schema.prisma）：用一种简洁的语法描述你的表，相当于昨天那份设计文档的“代码版”。可以把它想成盖房子：schema 是图纸，Migrate 是施工队，按图纸把房子盖出来或者改造；Client 是房子的门禁卡，按图纸上的房间做好，想进哪个房间刷哪张卡。
前面的课件一直说“不写死版本号”，这次是个例外，请特别注意。Prisma 正处在从 7 到 8 的过渡期，Prisma 8 是一次大改写，配置文件、命令、schema 写法都和 7 不一样，npm 上默认的最新版可能已经指向 8。这门课按 Prisma 7 写，Prisma 官方文档说明 7 仍然完整支持。所以安装时要写 prisma@7、@prisma/client@7，锁住大版本号，小版本仍然会自动取最新的。
Prisma 7 相比更早的版本也有几个变化，网上很多旧教程还是旧写法，看到时要能分辨：
schema.prisma 里，而是写在一个 TypeScript 配置文件里。7.10 以后 prisma init 生成的文件叫 prisma7.config.ts（为了和 Prisma 8 的 prisma.config.ts 区分），更早的 7.x 生成的叫 prisma.config.ts，Prisma 7 两个名字都认。下文统一写 prisma7.config.ts，如果你的文件叫另一个名字，照改即可。provider = "prisma-client"，并且必须指定 output，生成的代码放在你的项目里，从这个位置导入，而不是从 @prisma/client 导入。@prisma/adapter-pg，它底层用的是 Node.js 里最常用的 PostgreSQL 驱动 pg。prisma migrate dev 不再自动生成 Client，也不再自动运行种子脚本，要分别运行 prisma generate 和 prisma db seed。这些都以 Prisma 官方文档的 v7 部分为准。遇到和课件不一样的地方，先看你电脑上生成的文件长什么样，再去文档里查。
把昨天的设计写成 Prisma schema，是这样的：
dongge-web/prisma/schema.prisma
generator client {
provider = "prisma-client"
output = "../app/generated/prisma"
}
datasource db {
provider = "postgresql"
}
model World {
id Int @id @default(autoincrement())
slug String @unique
name String
feeling String
looks Look[]
@@map("worlds")
}
model Look {
id Int @id @default(autoincrement())
title String
description String
imageUrl String? @map("image_url")
published Boolean @default(false)
createdAt DateTime @default(now()) @map("created_at")
worldId Int @map("world_id")
world World @relation(fields: [worldId], references: [id])
@@index([worldId])
@@map("looks")
}
enum QuestionStatus {
PENDING
APPROVED
HIDDEN
@@map("question_status")
}
model Question {
id Int @id @default(autoincrement())
content String
nickname String?
status QuestionStatus @default(PENDING)
answer String?
createdAt DateTime @default(now()) @map("created_at")
@@map("questions")
}从上往下读：
generator client：告诉 Prisma 生成什么、放在哪。output 是相对于 schema 文件的路径，../app/generated/prisma 就是项目根目录下的 app/generated/prisma。datasource db：用的是 PostgreSQL。地址不写在这里，写在配置文件里。model World { ... }：一个 model 对应一张表。每一行是“字段名 类型 属性”。类型有 Int（整数）、String（文字）、Boolean、DateTime，类型后面加 ? 表示可以为空，对应 SQL 里没有 NOT NULL 的列。@ 开头的是字段属性：@id 主键，@default(autoincrement()) 自动递增，就是昨天的 SERIAL；@unique 不重复；@default(false)、@default(now()) 默认值。@map("image_url") 和 @@map("looks")：TypeScript 里习惯用驼峰命名（imageUrl、Look），数据库里习惯用小写加下划线（image_url、looks）。@map 负责翻译列名，@@map 负责翻译表名。这样你写代码时用 look.createdAt，数据库里的表和你昨天设计的一模一样，以后直接写 SQL 统计也方便。两个 @ 的属性作用于整个 model，一个 @ 的作用于单个字段。Look 里有两行：worldId Int 是真正存在数据库里的外键列；world World @relation(fields: [worldId], references: [id]) 不会变成数据库里的列，它告诉 Prisma“用我的 worldId 对上 World 的 id”，这样你查穿搭时可以顺手把世界带出来。World 里的 looks Look[] 是反方向，表示一个世界有一组穿搭，同样不占数据库的列。@@index([worldId])：昨天说的外键索引。enum QuestionStatus：枚举，只允许三个值。昨天设计用的是 CHECK 约束，Prisma 里用枚举效果一样：数据库拒绝别的值；额外的好处是 TypeScript 也知道 status 只能是这三个字符串，写错会标红。推荐在 VS Code 里装官方的 Prisma 扩展，.prisma 文件会有颜色和自动补全，保存时还会自动排版对齐。
写好 schema，数据库并不会自己变。运行：
npx prisma migrate dev --name initPrisma 会做三件事：对比 schema 和数据库现状，算出差别；把差别写成一个 SQL 文件，放在 prisma/migrations/时间戳_init/migration.sql；在数据库里执行它，并在一张叫 _prisma_migrations 的表里记下“这个迁移已经执行过”。
迁移文件就像数据库结构的 Git 提交记录。每改一次 schema，就生成一个新的迁移文件，按时间排好。好处是：上线时（DAY 54），Prisma 可以把这些迁移按顺序在正式数据库里执行一遍，线上的表结构和你本地的完全一致；换一台电脑、换一个数据库，也能一键还原。所以迁移文件要提交到 Git，而且生成以后不要手动去改它。
打开生成的 migration.sql，你会看到熟悉的 CREATE TABLE "worlds"、CREATE UNIQUE INDEX、ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY，和你昨天手写的设计几乎一样。这就是前两天学 SQL 的回报：你能看懂工具替你做了什么。
migrate dev 只用于开发阶段。它运行时会临时建一个“影子数据库”来检查迁移历史有没有问题，用完就删，这是正常的。如果它发现数据库和迁移记录对不上，可能会提示需要重置数据库、清空数据，这时先停下来看清楚提示，开发库里的示例数据可以用种子脚本重新写回来。
迁移之后还要运行 npx prisma generate，按最新的 schema 重新生成 Prisma Client。在 Prisma 7 里这一步不会自动发生，忘了的话，代码里就看不到新加的字段。
生成的 Client 以 model 名的小写开头：prisma.world、prisma.look、prisma.question。常用的方法和昨天的 SQL 一一对应：
// SELECT * FROM looks WHERE published = true ORDER BY created_at DESC
const looks = await prisma.look.findMany({
where: { published: true },
orderBy: { createdAt: 'desc' },
})
// 顺便把每套穿搭所属的世界带出来（相当于 JOIN）
const looksWithWorld = await prisma.look.findMany({
include: { world: true },
})
// 按唯一字段找一条，找不到返回 null
const street = await prisma.world.findUnique({ where: { slug: 'street' } })
// INSERT
await prisma.question.create({
data: { content: '泰拳训练一次大概多久？', nickname: '阿May' },
})
// UPDATE ... WHERE id = 2
await prisma.look.update({ where: { id: 2 }, data: { published: true } })
// DELETE ... WHERE id = 7
await prisma.look.delete({ where: { id: 7 } })
// SELECT COUNT(*) FROM questions
const total = await prisma.question.count()几个细节：所有方法都返回 Promise，要 await；条件写在 where 对象里，字段名用的是 schema 里的驼峰名；include: { world: true } 查出的每套穿搭会多一个 world 属性，里面是完整的世界对象，这就是 schema 里那两行关系字段的用处。update 和 delete 的 where 必须用 id 或 @unique 字段，Prisma 从设计上就不让你用这两个方法“不小心改掉整张表”，比手写 SQL 安全。
数据库地址是一串带密码的连接字符串，放在项目根目录的 .env 文件里，变量名是 DATABASE_URL。create-next-app 生成的 .gitignore 已经忽略了所有 .env 开头的文件，所以它不会被提交。记住三条：不提交到 Git，不贴到聊天里，不截图发给任何人。万一泄露了，去 Neon 重置这个角色的密码。
为什么放 .env 而不是 .env.local？Next.js 两个都会读，但 Prisma 的命令行工具只通过 dotenv 读 .env。放在 .env 里，网站和 Prisma 命令都能读到同一个值。
在 Neon 复制连接字符串时，要把 Connection pooling 开关关掉，拿“直连”地址（主机名里没有 -pooler）。Prisma 的迁移命令需要直连数据库，连接池那条路不支持它要用的一些功能。对个人官网来说，网站本身也用这个直连地址完全够用。
然后在 lib/prisma.ts 里创建一个全站共用的 Prisma Client：
dongge-web/lib/prisma.ts
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '@/app/generated/prisma/client'
const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }
function createPrismaClient() {
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
return new PrismaClient({ adapter })
}
const prisma = globalForPrisma.prisma ?? createPrismaClient()
if (process.env.NODE_ENV !== 'production') {
globalForPrisma.prisma = prisma
}
export default prisma逐行看：从生成的目录导入 PrismaClient，从适配器包导入 PrismaPg。createPrismaClient 用 DATABASE_URL 创建适配器，再把适配器交给 PrismaClient。中间那几行是为了解决开发时的一个问题：npm run dev 下你每保存一次文件，Next.js 都会重新加载代码，如果每次都新建一个 Client，数据库连接会越积越多。所以把创建好的 Client 挂在 globalThis（一个在重新加载时不会被清掉的全局对象）上，下次先看那里有没有现成的。?? 的意思是“左边是 null 或 undefined 时才用右边”。上线的生产环境不会反复重新加载，所以只在非生产环境这么做。这段是官方推荐的固定写法，理解思路即可。
最后，页面里查数据库前要加一句 await connection()。Next.js 默认会尽量在构建时把页面提前生成好，如果不加这句，上线后首页可能一直显示构建那一刻的穿搭，你新增的内容要等下次部署才出现。connection() 告诉 Next.js：“这个页面要等真实访客来了再生成，每次都查最新数据。”开发模式下看不出区别，但上线后很重要，现在就养成习惯。
查资料时你会看到很多教程（包括 Neon 自己的 Prisma 指南）用的是 npx prisma db push，而不是 migrate dev。两者的区别：db push 直接把数据库改成 schema 的样子，不生成迁移文件，不留记录，适合随手试验的原型；migrate dev 每次都留下一个迁移文件，适合要长期维护、要上线的项目。你的官网要一直用到第 72 天，还要把同样的结构搬到正式环境，所以我们用 migrate dev。两种方式不要混着用，否则迁移记录和数据库对不上，下次迁移时 Prisma 会要求重置数据库。
还有一个容易混淆的地方：Neon 的指南会让你准备两个连接地址，一个走连接池给网站用，一个直连给 Prisma 命令用。那是面向访问量很大的网站的做法。你的官网访问量不大，课程里统一只用一个 DATABASE_URL，填直连地址，网站和命令都用它，配置最简单，也不容易出错。
今天的分工按“结对搭档”的规矩来：schema 是今天的核心，由你自己写，Claude 只在 Plan 模式里给方案、解释属性；种子脚本的框架（创建 Client、断开连接、错误处理）是样板，交给 Claude，但数据和“有则跳过”的判断你要读懂；首页的查询你照着课件写，世界页的查询你独立完成。每次 Claude 改完文件，都用 git diff 看一遍，看不懂的行直接问它“这一行删掉会怎样”。
明天开始，数据的流向会反过来：不只是从数据库读出来给访客看，还要把粉丝在网页上写的提问存进数据库。
安装 Prisma 7 和相关的包
cd ~/code/dongge-web
npm install prisma@7 tsx @types/pg --save-dev
npm install @prisma/client@7 @prisma/adapter-pg@7 pg dotenv
npx prisma -v第一行装的是只在开发时用的工具：Prisma 命令行、用来运行 TypeScript 脚本的 tsx、pg 的类型定义。第二行装的是网站运行时要用的：Prisma Client、PostgreSQL 适配器、pg 驱动、读 .env 的 dotenv。
npx prisma -v 显示的 prisma 和 @prisma/client 版本都以 7. 开头。如果看到 8.，说明装错了，按“常见问题”第一条处理。初始化 Prisma
npx prisma init --datasource-provider postgresql --output ../app/generated/prisma --no-skills--output 指定生成的 Client 放在哪；--no-skills 表示先不安装 Prisma 给 AI 编程助手准备的附加说明文件，保持项目干净。命令会创建 prisma/schema.prisma、prisma7.config.ts（或 prisma.config.ts）和 .env，并在 .gitignore 末尾加上 /app/generated/prisma。生成的代码不提交，每次安装依赖后重新生成就行。
cat .gitignore 最后一行是 /app/generated/prisma，而且上面仍然有 .env* 这一行。把 Neon 的直连地址放进 .env
打开 Neon 控制台里的 dongge-web 项目，点 Connect。分支选 production，数据库选 neondb（不是 practice），把 Connection pooling 开关关掉，复制连接字符串。在 VS Code 里打开项目根目录的 .env，把 prisma init 写进去的示例地址整行替换成：
dongge-web/.env
DATABASE_URL="postgresql://用户名:密码@ep-xxxx.ap-southeast-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require"引号里换成你复制的完整字符串，要在同一行，不能断开。确认主机名里没有 -pooler，数据库名是 neondb。然后看一眼 git status，.env 不应该出现在列表里。
写 schema（Claude 出方案，你来写）
切到 Plan 模式，发送 claude 部分的第一条提示词，让 Claude 对照你的 docs/database.md 给出 schema 方案。把它的方案和上午第 3 节对照，有差异的地方问清楚。然后你自己打开 prisma/schema.prisma，在 generator 和 datasource 下面写出三个 model 和一个 enum。写完运行：
npx prisma format
npx prisma validateformat 把你的 schema 排版对齐，validate 显示 schema 有效。第一次迁移
npx prisma migrate dev --name init
npx prisma generate运行 Prisma 命令时，终端可能会问一次是否安装 Prisma 的 agent skills（给 AI 编程助手的附加说明），和第 2 步的 --no-skills 保持一致，输入 n 回车就好，不回答它 30 秒后也会自动跳过。
然后打开 prisma/migrations 里新生成的文件夹，读一遍 migration.sql，找到三条 CREATE TABLE、外键约束和 world_id 上的索引，和昨天的设计逐条对照。
neondb 数据库出现了 worlds、looks、questions 和 _prisma_migrations 四张表；项目里出现了 app/generated/prisma 文件夹。配置种子脚本
打开 prisma7.config.ts，在 migrations 里加一行 seed，告诉 Prisma 运行 prisma db seed 时执行哪个命令：
dongge-web/prisma7.config.ts
// This file was generated by Prisma, and assumes you have installed the following:
// npm install --save-dev prisma dotenv
import "dotenv/config";
import { defineConfig } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
seed: "tsx prisma/seed.ts",
},
datasource: {
url: process.env["DATABASE_URL"],
},
});第一行 import "dotenv/config" 负责把 .env 读进来，删了它 Prisma 就找不到数据库地址。你电脑上生成的文件可能和这里略有不同，只要加上 seed 那一行就行。
再打开 package.json，在 scripts 里加一行 postinstall：
dongge-web/package.json（片段）
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint",
"postinstall": "prisma generate"
}postinstall 会在每次 npm install 之后自动运行。因为生成的 Client 不提交到 Git，以后在 Vercel 上构建、在 GitHub Actions 里跑测试，装完依赖都会自动生成一次。
写种子脚本（样板给 Claude，数据你来定）
种子脚本（seed）用来往数据库里放初始数据。让 Claude 按 claude 部分第二条提示词写出样板，然后对照下面的版本逐行读懂，把穿搭描述和提问换成你自己的话：
dongge-web/prisma/seed.ts
import 'dotenv/config'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '../app/generated/prisma/client'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })
const worldData = [
{ slug: 'gentleman', name: '绅士', feeling: '安全感' },
{ slug: 'street', name: '街头', feeling: '心动' },
{ slug: 'thai', name: '泰风', feeling: '被保护感' },
]
async function main() {
// 1. 世界：按 slug 有则更新、无则创建，重复运行也不会多出来
for (const world of worldData) {
await prisma.world.upsert({
where: { slug: world.slug },
update: { name: world.name, feeling: world.feeling },
create: world,
})
}
const worlds = await prisma.world.findMany()
function worldId(slug: string) {
const found = worlds.find((world) => world.slug === slug)
if (!found) {
throw new Error(`找不到世界：${slug}`)
}
return found.id
}
// 2. 穿搭：只在表是空的时候写入，避免重复运行时插入重复数据
if ((await prisma.look.count()) === 0) {
await prisma.look.createMany({
data: [
{ title: '深灰马甲配白衬衫', description: '打斯诺克那天穿的，袖子挽到小臂。', published: true, worldId: worldId('gentleman') },
{ title: '棕色皮鞋和西裤', description: '鞋头擦过一遍，站在球台边不抢戏。', published: true, worldId: worldId('gentleman') },
{ title: 'Baggy 裤配 Vans', description: '骑 BMX 不卡腿，摔了也不心疼。', published: true, worldId: worldId('street') },
{ title: 'Oversize 白 T', description: '滑板公园的标准装，风一吹就鼓起来。', published: true, worldId: worldId('street') },
{ title: '红色泰拳短裤', description: '训练完绑带还没拆。', published: true, worldId: worldId('thai') },
{ title: '泰式印花衬衫', description: '打完拳去吃泰餐时换上的那件。', published: false, worldId: worldId('thai') },
],
})
}
// 3. 示例提问：两条已通过并有回答，一条待审核
if ((await prisma.question.count()) === 0) {
await prisma.question.createMany({
data: [
{
content: '打斯诺克前你会先做什么？',
nickname: '小鹿',
status: 'APPROVED',
answer: '先擦杆头，再看一眼台面上的球。动作慢下来，心也就静了。',
},
{
content: '滑板摔了还会继续吗？',
status: 'APPROVED',
answer: '会。先看手腕和膝盖有没有事，没事就再上板，这次放慢一点。',
},
{
content: '泰拳训练一次大概多久？',
nickname: '阿May',
},
],
})
}
console.log('种子数据写入完成')
}
main()
.then(async () => {
await prisma.$disconnect()
})
.catch(async (error) => {
console.error(error)
await prisma.$disconnect()
process.exit(1)
})要读懂的几个点：种子脚本是在网站之外单独运行的，所以要自己 import 'dotenv/config' 读 .env，自己创建 Client，用完 $disconnect() 断开连接。upsert 是 update 和 insert 的合体：找得到就更新，找不到就创建。createMany 一次插入多行。每一部分都先判断“已经有了就不写”，所以这个脚本可以放心重复运行，以后在后台加了真实的穿搭，再跑一次种子也不会删掉或重复它们。第三条提问没写 status，会用默认的 PENDING。
npx prisma db seed
npx prisma studioprisma studio 会在浏览器打开一个数据管理界面，能看到 3 个世界、6 套穿搭、3 条提问。再运行一次 npx prisma db seed，数量不变。看完在终端按 Ctrl + C 关掉 Studio。创建 lib/prisma.ts
把上午第 6 节的代码写进 lib/prisma.ts，这一段是固定写法，可以复制，但要能讲出每一行在做什么。
首页改为从数据库读取穿搭
把 app/page.tsx 改成下面这样。三个世界的卡片暂时还用 lib/data/worlds.ts 里的数据，只有穿搭换成数据库：
dongge-web/app/page.tsx
import Link from 'next/link'
import { connection } from 'next/server'
import LookFilter from '@/components/LookFilter'
import prisma from '@/lib/prisma'
import type { Look, World } from '@/lib/types'
import { worlds } from '@/lib/data/worlds'
export default async function Home() {
await connection()
const rows = await prisma.look.findMany({
where: { published: true },
orderBy: { createdAt: 'desc' },
include: { world: true },
})
const looks: Look[] = rows.map((row) => ({
id: row.id,
title: row.title,
description: row.description,
world: row.world.slug as World,
}))
return (
<div className="space-y-10">
<section>
<h1 className="text-3xl font-bold">三岁的东哥</h1>
<p className="mt-2 text-gray-600">在外面是绅士、拳手、潮男，在你面前三岁。</p>
</section>
<section>
<h2 className="text-xl font-semibold">三个世界</h2>
<ul className="mt-4 grid gap-4 sm:grid-cols-3">
{worlds.map((world) => (
<li key={world.slug}>
<Link
href={`/world/${world.slug}`}
className="block rounded-xl border p-4 hover:bg-gray-50"
>
<p className="text-lg font-semibold">{world.name}</p>
<p className="text-sm text-gray-500">给你{world.feeling}</p>
</Link>
</li>
))}
</ul>
</section>
<section>
<h2 className="text-xl font-semibold">最近的穿搭</h2>
<div className="mt-4">
<LookFilter looks={looks} />
</div>
</section>
</div>
)
}注意 rows.map 这一步：数据库查出的每一行有很多字段，还带着整个世界对象，而 LookFilter 和 LookCard 只需要四个字段，所以把它“整理”成你原来定义的 Look 类型再传过去。这样组件一行都不用改，传进浏览器的数据也只有这几项。数据库里的 slug 类型是普通字符串，而 Look 要求它是三个世界之一，as World 是告诉 TypeScript“我保证它是”，因为数据是种子脚本写进去的，这个保证成立。
世界页改为从数据库读取（你来写）
参照首页，自己改 app/world/[slug]/page.tsx：删掉 generateStaticParams，加上 await connection()，用 prisma.world.findUnique 按 slug 查世界，同时用 include 带出它已发布的穿搭，按时间倒序；找不到就 notFound()。世界的介绍文案 tagline 还留在 lib/data/worlds.ts 里。写完再对照：
dongge-web/app/world/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { connection } from 'next/server'
import LookCard from '@/components/LookCard'
import prisma from '@/lib/prisma'
import type { World } from '@/lib/types'
import { worlds } from '@/lib/data/worlds'
export default async function WorldPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
await connection()
const { slug } = await params
const world = await prisma.world.findUnique({
where: { slug },
include: {
looks: {
where: { published: true },
orderBy: { createdAt: 'desc' },
},
},
})
if (!world) {
notFound()
}
const tagline = worlds.find((item) => item.slug === world.slug)?.tagline
return (
<div className="space-y-6">
<header>
<p className="text-sm text-gray-500">给你{world.feeling}</p>
<h1 className="text-3xl font-bold">{world.name}</h1>
{tagline && <p className="mt-2 text-gray-600">{tagline}</p>}
</header>
{world.looks.length === 0 ? (
<p className="text-gray-500">这个世界的穿搭还在路上。</p>
) : (
<div className="grid gap-4 sm:grid-cols-2">
{world.looks.map((look) => (
<LookCard
key={look.id}
look={{
id: look.id,
title: look.title,
description: look.description,
world: world.slug as World,
}}
/>
))}
</div>
)}
</div>
)
}/world/thai 显示泰风已发布的穿搭，/world/boxing 仍然是 404。现在 lib/data/looks.ts 已经没人用了，用 grep -rn "data/looks" app components lib 确认没有输出后，把它删掉。检查并提交
npm run lint
npm run build
git status
git add .
git commit -m "接入 Prisma 7 和 Neon：三张表、种子数据、首页和世界页读数据库"
git push如果 npm run lint 输出了一串来自 app/generated 的警告，那是 ESLint 在检查 Prisma 生成的代码。生成的代码不归你管，打开 eslint.config.mjs，在 globalIgnores([...]) 的数组里加一项 "app/generated/**"，让 ESLint 跳过它。
git status 里能看到 prisma/、prisma7.config.ts、lib/prisma.ts，看不到 .env 和 app/generated。如果看到 .env，立刻停下，不要提交，先检查 .gitignore。npx prisma -v 显示 8.x，或者 prisma init 生成的文件和课件完全对不上：装成了 Prisma 8。运行 npm uninstall prisma @prisma/client，再按第 1 步带 @7 重新安装；如果已经生成了陌生的文件，用 git status 找出来删掉，再重新 init。@/app/generated/prisma/client：还没生成 Client。运行 npx prisma generate。每次改完 schema、迁移完，都要再运行一次。P1001: Can't reach database server 或提示找不到 DATABASE_URL：检查 .env 是否在项目根目录（和 package.json 同级）、变量名是否拼对、连接字符串是否完整在一行里；配置文件第一行的 import "dotenv/config" 有没有被删掉。Neon 休眠后第一次连接会慢一点，重试一次。looks 表不存在：迁移没跑成功，或者 .env 里的数据库名写成了 practice。确认连接字符串里是 /neondb，再运行 npx prisma migrate dev。migrate dev 提示需要重置数据库、所有数据会丢失：数据库里的表和迁移记录对不上，常见于在 Neon 编辑器里手动改过 neondb 的表。开发阶段可以同意重置，然后 npx prisma db seed 把示例数据写回来。以后正式库里有真实数据时，绝不能随手同意。改了 schema 之后要做什么，数据库才会跟着变？
运行 npx prisma migrate dev --name 这次改动的名字。Prisma 会对比 schema 和数据库的差别，生成一个新的迁移 SQL 文件并在数据库里执行。然后运行 npx prisma generate，让 Prisma Client 的代码和类型跟上新的 schema（Prisma 7 不会自动做这一步）。最后把新的迁移文件提交到 Git，上线时用它把同样的改动应用到正式数据库。只改 schema 不迁移，数据库不会有任何变化。
schema 里 Look 有 worldId 和 world 两个字段，它们有什么区别？数据库里有几列？
worldId 是真实存在数据库里的外键列（通过 @map 叫 world_id），存的是世界的 id。world 是关系字段，不会变成数据库的列，它告诉 Prisma 用 worldId 去对 World 的 id，让你能用 include: { world: true } 把世界一起查出来。所以和世界有关的只有 world_id 一列。
为什么种子脚本可以放心重复运行？如果把“表是空的才写入”那个判断去掉会怎样？
世界用 upsert 按唯一的 slug 写入，存在就更新、不存在才创建，不会重复；穿搭和提问在写入前先 count()，已经有数据就跳过。去掉判断后，每运行一次就会再插入 6 套穿搭和 3 条提问，数据越来越多、全是重复的；以后后台加了真实内容，也会和示例数据混在一起。
'use server' 的作用。<form action={...}> 和 FormData 把粉丝的提问存进数据库，做出“粉丝提问箱”的第一版。revalidatePath 解决什么问题，提交后页面上的数据会立刻更新。DAY 21 和 DAY 30 你做过“给东哥留言”的表单，提交后存在访客浏览器的 localStorage 里。问题是，这些留言只有访客自己的浏览器里有，你根本看不到。要让留言真正送到你手里，数据必须从访客的手机出发，送到服务器，再存进数据库。
传统做法要写好几层：先在服务器上写一个“接口”，规定好网址和数据格式；再在页面里用 DAY 22 学的 fetch 发一个 POST 请求，把表单内容转成 JSON 发过去；接口收到后解析、存库、返回结果；页面再根据结果更新界面。每一层都要自己写，每一层都可能出错。
Next.js 的 Server Action 把这几层合成了一步：你写一个普通的 async 函数，标上 'use server'，然后直接交给表单的 action。访客点提交，这个函数就在服务器上运行，中间怎么发请求、怎么传数据，Next.js 全部替你做好。
比喻一下：以前是你把点菜单拍照、发消息给后厨、后厨回消息确认；现在是餐桌上有一个传菜口，点菜单往里一塞，直接落到后厨的案板上，做完端出来。
dongge-web/app/ask/actions.ts
'use server'
import { revalidatePath } from 'next/cache'
import prisma from '@/lib/prisma'
export async function submitQuestion(formData: FormData) {
const content = String(formData.get('content') ?? '').trim()
const nickname = String(formData.get('nickname') ?? '').trim()
if (content === '' || content.length > 200) {
return
}
await prisma.question.create({
data: {
content,
nickname: nickname === '' ? null : nickname.slice(0, 20),
},
})
revalidatePath('/ask')
}逐行看：
'use server' 写在文件最顶上，表示这个文件里导出的所有函数都是 Server Action。注意别和昨天的 'use client' 搞混：'use client' 标记“这个组件要送进浏览器”，'use server' 标记“这些函数留在服务器，但允许浏览器调用”。submitQuestion 必须是 async 函数。表单调用它时，会自动把表单内容打包成一个 FormData 对象作为参数传进来。formData.get('content') 按表单字段的 name 取值。它的返回值可能是字符串、可能是上传的文件、也可能是 null（字段不存在时），所以先用 ?? '' 把 null 换成空字符串，再用 String() 转成字符串，最后 trim() 去掉首尾空格。return，什么都不存。这是最简陋的检查，明天会用 Zod 换掉它，并把错误提示显示给粉丝。prisma.question.create 把一条提问写进数据库。只写 content 和 nickname 两个字段，status 用数据库的默认值 PENDING，answer 为空，createdAt 自动填当前时间。昵称没填就存 null，填了最多保留 20 个字。revalidatePath('/ask')，下一节讲。这里有一个很重要的设计决定：存什么由服务器决定，而不是由表单决定。表单只提供内容和昵称，状态永远是“待审核”。如果有人在浏览器里伪造一个 status=APPROVED 的字段，我们的代码根本不读它，他的提问也不会跳过审核直接公开。DAY 45 讲安全时会专门回到这一点。
在页面里，把 Server Action 交给 <form> 的 action：
dongge-web/app/ask/page.tsx（表单部分）
<form action={submitQuestion}>
<label htmlFor="content">你的问题</label>
<textarea id="content" name="content" rows={4} required maxLength={200} />
<label htmlFor="nickname">昵称（可以不填）</label>
<input id="nickname" name="nickname" maxLength={20} />
<button type="submit">投进提问箱</button>
</form>和你 DAY 21 写的表单相比，最大的区别是：不需要 onSubmit，不需要 preventDefault，不需要自己读输入框的值。浏览器按每个字段的 name 收集内容，React 把它们打包成 FormData 交给 submitQuestion。所以 name 属性一定要写，而且要和 action 里 formData.get() 的名字一致；label 的 htmlFor 对上输入框的 id，这是 DAY 05 讲过的无障碍习惯。
required 和 maxLength 是浏览器自带的检查：不填内容点不了提交，超过 200 字打不进去。它们能挡住普通访客的手误，但挡不住故意绕过的人，所以服务器上那几行检查不能省。
这个页面本身是服务端组件，表单里没有任何 useState 和 onClick，不需要 'use client'。它还有一个好处叫渐进增强：就算访客的浏览器还没加载完 JavaScript，甚至关掉了 JavaScript，表单照样能提交，只是会整页刷新一次。提交成功后，React 会自动清空表单里的输入框。
提问箱页面上会显示“已经收到几个问题”和“东哥回答过的问题”。粉丝提交一条新问题后，数字应该加一。但 Next.js 为了快，会在浏览器和服务器上缓存已经渲染过的页面结果，如果什么都不做，提交完看到的可能还是旧的数字。
revalidatePath('/ask') 的意思是：“/ask 这个页面的数据过期了，请重新生成。”在 Server Action 里调用它，Next.js 会在同一次请求里顺便把 /ask 重新渲染一遍，把新的页面结果和 action 的结果一起送回浏览器，页面上的数字立刻更新，不用访客手动刷新。
你可能会问：页面里已经写了 await connection()，每次访问都会重新查数据库，为什么还要 revalidatePath？因为缓存不只在服务器上。浏览器这边的 Next.js 路由也会记住刚看过的页面结果，方便你前进后退时瞬间显示。revalidatePath 同时通知了两边：服务器重新渲染，浏览器丢掉旧的结果。少了它，服务器的数据是新的，访客眼前的页面却还是旧的。
规则很简单：Server Action 改了哪些页面要显示的数据，就对那些页面调用 revalidatePath。比如 DAY 48 你在后台新增一套穿搭，就要对首页 / 和对应的世界页调用它。
还有一个相关的函数 redirect('/某个网址')，来自 next/navigation，用来在 action 做完后跳转到别的页面，比如“发布成功后跳回列表页”。它会立即中止后面的代码，所以要放在 revalidatePath 之后。今天的提问箱不需要跳转，留在原页面就好。
把前面几节串起来，粉丝点下“投进提问箱”后发生的事：
粉丝的手机（浏览器） 你的服务器（Next.js） Neon 数据库
1. 填写问题，点提交
2. 浏览器按 name 收集字段，
打包成 FormData
3. 发出一个 POST 请求 ───────────────→ 4. 根据请求里的 action 编号
（带着 action 编号和表单内容） 找到 submitQuestion 并运行
5. 读取、清理、检查内容
6. prisma.question.create ─────→ 7. 执行 INSERT，
新增一行，status 为 PENDING
8. revalidatePath('/ask')，
重新渲染提问箱页面
9. 收到新的页面结果， ←─────────────── 把结果送回浏览器
数字加一，表单清空第 3 步的“action 编号”是 Next.js 构建时给每个 Server Action 生成的一个加密编号，浏览器只知道这个编号，不知道函数里写了什么，函数的代码永远留在服务器上。第 6、7 步里，Prisma 把 create 翻译成你 DAY 40 手写过的 INSERT INTO questions ...。
理解这张图最重要的一点：第 3 步是一个任何人都能发的普通 POST 请求。不一定来自你的页面，懂技术的人可以用工具直接发，内容想填什么填什么。所以第 5 步服务器上的检查才是真正的防线，浏览器里的 required 只是方便正常访客。明天的输入校验、后天的安全课，都是在加固第 5 步。
Server Action 适合“自己网站的表单和按钮”。如果要给别的程序提供数据，比如以后做一个手机 App 要读你的穿搭列表，或者别的服务在某件事发生时通知你的网站，就用 Route Handler。它是 app 里一个叫 route.ts 的约定文件，按 HTTP 方法导出函数：
dongge-web/app/api/worlds/route.ts
import prisma from '@/lib/prisma'
export async function GET() {
const worlds = await prisma.world.findMany({
orderBy: { id: 'asc' },
select: { slug: true, name: true, feeling: true },
})
return Response.json(worlds)
}访问 /api/worlds，浏览器就会收到一段 JSON。函数名 GET 对应 HTTP 的 GET 请求，还可以导出 POST、DELETE 等。select 只挑出三个要公开的字段，接口返回的东西谁都能看到，所以只给该给的。Response.json() 是浏览器标准里就有的写法，把对象转成 JSON 响应。
两个规矩：同一个文件夹里不能同时有 page.tsx 和 route.ts，所以接口习惯放在 app/api/ 下面；GET 只用来读数据，不要在 GET 里修改数据，因为浏览器、搜索引擎、预取都可能随手发 GET 请求。你的官网目前所有写入操作都用 Server Action，Route Handler 知道它是什么、什么时候用就够了。
Server Action 写起来像普通函数，但它背后是一次网络请求，所以有几条和普通函数不一样的规矩，先记住，后面几天会一条条用上：
这些规矩背后是同一个思路：浏览器是访客的地盘，服务器是你的地盘，所有从浏览器来的东西，进你的地盘之前都要检查。今天的第一版提问箱只做了最基本的检查，接下来两天会把它加固成一个真正能上线的功能。
让 Claude 出方案（Plan 模式）
发送 claude 部分的第一条提示词。对照上午的内容检查它的方案：文件放在哪、表单字段叫什么、action 里存哪些字段、提交后怎么更新页面。特别留意它有没有让表单决定 status，如果有，指出来。确认方案后再动手。
写 Server Action（你来写）
mkdir -p app/ask新建 app/ask/actions.ts，照上午第 2 节自己敲一遍。敲完不看课件，对着代码给自己讲一遍每行在做什么。
写提问箱页面
表单的 Tailwind 样式可以让 Claude 写样板（claude 部分第二条提示词），两个数据库查询你自己写。完整页面如下，对照检查：
dongge-web/app/ask/page.tsx
import type { Metadata } from 'next'
import { connection } from 'next/server'
import prisma from '@/lib/prisma'
import { submitQuestion } from './actions'
export const metadata: Metadata = {
title: '提问箱 | 三岁的东哥',
}
export default async function AskPage() {
await connection()
const total = await prisma.question.count()
const answered = await prisma.question.findMany({
where: { status: 'APPROVED' },
orderBy: { createdAt: 'desc' },
select: { id: true, content: true, nickname: true, answer: true },
})
return (
<div className="space-y-10">
<section className="space-y-2">
<h1 className="text-2xl font-bold">粉丝提问箱</h1>
<p className="text-gray-600">想问东哥什么，写在这里。看过之后，会挑一些在下面回答。</p>
<p className="text-sm text-gray-500">提问箱里已经有 {total} 个问题。</p>
</section>
<form action={submitQuestion} className="space-y-4 rounded-2xl border p-6">
<div>
<label htmlFor="content" className="block text-sm font-medium">
你的问题
</label>
<textarea
id="content"
name="content"
rows={4}
required
maxLength={200}
placeholder="比如：打斯诺克前你会做什么准备？"
className="mt-1 w-full rounded-lg border p-3"
/>
</div>
<div>
<label htmlFor="nickname" className="block text-sm font-medium">
昵称（可以不填）
</label>
<input
id="nickname"
name="nickname"
maxLength={20}
className="mt-1 w-full rounded-lg border p-3"
/>
</div>
<button type="submit" className="rounded-full bg-black px-6 py-2 text-white">
投进提问箱
</button>
</form>
<section className="space-y-4">
<h2 className="text-xl font-semibold">东哥回答过的</h2>
{answered.length === 0 ? (
<p className="text-gray-500">还没有公开的回答。</p>
) : (
<ul className="space-y-4">
{answered.map((question) => (
<li key={question.id} className="rounded-xl border p-4">
<p className="font-medium">{question.content}</p>
<p className="mt-1 text-xs text-gray-400">{question.nickname ?? '匿名'} 问</p>
{question.answer && (
<p className="mt-3 text-gray-700">东哥：{question.answer}</p>
)}
</li>
))}
</ul>
)}
</section>
</div>
)
}几个要注意的地方：where: { status: 'APPROVED' } 保证前台只显示审核通过的提问，新提交的问题是 PENDING，不会出现在这里；select 只取页面要显示的四个字段；{question.nickname ?? '匿名'} 在没留昵称时显示“匿名”。
/ask，看到“已经有 3 个问题”，下面是种子脚本写入的两条已回答的提问。把提问箱加进导航
打开 components/Nav.tsx，在 links 数组的“测试”后面加一项 { href: '/ask', label: '提问箱' }。
提交一条问题，去数据库里找它
在提问箱里写一条问题，比如“骑 BMX 最难学的动作是什么？”，昵称随便填，点提交。
运行 npx prisma studio 打开 questions 表，或者在 Neon 的 Tables 里选 neondb 看 questions 表，找到你刚提交的那一行：status 是 PENDING，answer 为空，created_at 是刚才的时间。再提交一条不填昵称的，确认 nickname 是 null 而不是空字符串。
在开发者工具里看这次请求
打开浏览器开发者工具的 Network 面板，再提交一次。找到一条方法为 POST、地址是 /ask 的请求，点开看它的请求内容（Payload），能看到你填的问题文字。这就是上午旅程图里的第 3 步。
关掉 JavaScript 再提交一次
在开发者工具里按 Cmd + Shift + P，输入 Disable JavaScript 回车，然后刷新 /ask，再提交一条问题。
Enable JavaScript 打开回来。绕过浏览器检查，看服务器能不能挡住
在开发者工具的 Elements 面板里找到 textarea，双击删掉它的 required 属性。然后在输入框里只打几个空格，点提交。
content === '' 那一行挡住了它。问题是粉丝完全不知道发生了什么，页面没有任何提示，这是明天要解决的。写一个 Route Handler
mkdir -p app/api/worlds新建 app/api/worlds/route.ts，内容见上午第 6 节。打开 http://localhost:3000/api/worlds。
检查并提交
npm run lint
npm run build
git add .
git commit -m "粉丝提问箱第一版：Server Action 存入数据库"
git push测试时提交的那几条问题留在开发库里没关系，DAY 50 做审核功能时正好当测试数据。
null 字样：输入框的 name 和 formData.get() 里的名字对不上，比如一个写 content、一个写 question。FormData 只认 name，不认 id。'use server' 的文件里，导出的东西必须全部是 async 函数（TypeScript 的类型除外），不能导出普通常量、对象或普通函数。要共享的常量放到别的文件里。revalidatePath('/ask')，或者路径写错了（比如写成 'ask' 少了斜杠）。'use client' 的文件里写了带 'use server' 的函数。Server Action 要写在单独的 'use server' 文件里，客户端组件从那里导入。where: { status: 'APPROVED' } 里的值必须是枚举里的三个值之一，大小写要完全一致，写成 'approved' 会被 TypeScript 标红。表单提交后，数据是怎么从浏览器一路走到数据库的？
粉丝点提交后，浏览器按每个字段的 name 收集内容，打包成 FormData，连同 Next.js 生成的 action 编号一起，以 POST 请求发到服务器。Next.js 根据编号找到 submitQuestion，在服务器上运行它：读取并清理字段、做检查，然后用 prisma.question.create 写库，Prisma 把它翻译成 INSERT 语句发给 Neon，新增一行，状态默认是 PENDING。接着 revalidatePath('/ask') 让 Next.js 重新渲染提问箱页面，新的页面结果随响应一起回到浏览器，数字更新、表单清空。
浏览器里已经有 required 和 maxLength 了，为什么 Server Action 里还要再检查一次？
浏览器的检查只对正常使用页面的人有效，可以在开发者工具里删掉，也可以完全绕过页面，直接用工具向服务器发 POST 请求，内容随便填。服务器上的检查是所有请求都必须经过的地方，才是真正的防线。浏览器检查的价值是让正常访客更快知道自己填错了。
提问箱的写入用了 Server Action，/api/worlds 用了 Route Handler。什么时候该用哪个？
自己网站里的表单和按钮要修改数据时，用 Server Action，写法简单、和页面配合好，还自带渐进增强。需要给别的程序提供一个固定网址的接口时，用 Route Handler，比如手机 App 读取数据、第三方服务发来通知。Route Handler 的 GET 只用来读，不要在里面修改数据。
safeParse 校验表单数据，用 z.flattenError 取出每个字段的错误。useActionState 把服务器的结果送回表单：成功提示、字段错误、粉丝原来写的内容。pending 禁用按钮防止连点，并在服务器上挡住一分钟内的重复提交。昨天最后一个实验里，你删掉了输入框的 required，只打了几个空格就提交。服务器挡住了它，数据库里没有多出空提问，这很好。但暴露出两个问题：
content === ''、content.length > 200、nickname.slice(0, 20)，每条规则都是手写的 if 和字符串操作。字段一多，规则一复杂，很容易漏掉或写错。今天分别用两个工具解决：用 Zod 把规则集中写成一份“规则书”，用 React 的 useActionState 把服务器的检查结果送回页面，告诉粉丝哪里要改。
先回答一个根本问题：浏览器已经有 required、maxLength 了，为什么服务器还要查？因为浏览器是访客的地盘。页面上的一切，包括这些检查，都运行在访客的设备上，访客可以打开开发者工具随意修改，也可以完全不用你的页面，直接用工具向服务器发请求。你的服务器唯一能确定的，是“收到了一个请求”，至于里面装着什么，只能自己检查。前端校验是为了体验，让正常访客尽快知道自己填错了；服务端校验是为了安全和数据正确，谁也绕不过去。两者都要有，但只有后者是防线。
Zod 是一个“数据校验”库。你用它描述“一份合格的数据应该长什么样”，然后把收到的数据交给它，它告诉你合格不合格、哪里不合格。现在的版本是 Zod 4，安装命令是 npm install zod。
提问箱的规则书：
dongge-web/lib/question-schema.ts
import * as z from 'zod'
export const questionSchema = z.object({
content: z
.string({ error: '请先写下你的问题。' })
.trim()
.min(1, '请先写下你的问题。')
.min(5, '问题至少写 5 个字。')
.max(200, '问题最多 200 个字。'),
nickname: z
.string()
.trim()
.max(20, '昵称最多 20 个字。')
.nullish()
.transform((value) => value || null),
})
export type QuestionInput = z.infer<typeof questionSchema>逐行看：
import * as z from 'zod'：把 Zod 的所有功能导入成一个叫 z 的对象，这是 Zod 4 官方文档用的写法。z.object({ ... })：要校验的是一个对象，里面有 content 和 nickname 两个字段。z.string({ error: '...' })：content 必须是字符串。如果收到的是 null（表单里根本没有这个字段）或者一个文件，就报括号里这句错误。.trim()：先把首尾空格去掉，后面的检查都针对去掉空格之后的内容。所以只打空格会被当作空的。.min(1, ...)、.min(5, ...)、.max(200, ...)：长度检查，第二个参数是不满足时的提示。写两个 min，是为了让“完全没写”和“写得太短”显示不同的提示。.nullish() 表示这个字段可以是 null 或者不存在；.transform((value) => value || null) 在检查通过后把结果再加工一下：空字符串、null、不存在，统统变成 null。这样数据库里“没留昵称”只有一种样子。z.infer<typeof questionSchema>：从规则书自动推导出 TypeScript 类型，结果是 { content: string; nickname: string | null }。规则改了，类型跟着变，不用写两遍。这份规则书只依赖 Zod，不依赖数据库也不依赖页面，所以放在 lib 里。DAY 51 写单元测试时，你会专门给它写测试。
把数据交给规则书检查，用 safeParse：
const result = questionSchema.safeParse({
content: formData.get('content'),
nickname: formData.get('nickname'),
})
if (!result.success) {
const errors = z.flattenError(result.error).fieldErrors
// errors 形如 { content: ['问题至少写 5 个字。'] }
} else {
const { content, nickname } = result.data
// content 已经去掉首尾空格，nickname 是字符串或 null
}safeParse 返回一个对象：检查通过时 success 是 true，data 里是清理过的数据，已经去掉空格、做过 transform；不通过时 success 是 false，error 里是所有不合格的地方。Zod 还有一个 parse 方法，不通过时直接抛出错误；在 Server Action 里我们想把错误友好地告诉粉丝，而不是让程序崩掉，所以用 safeParse。
z.flattenError(result.error) 把错误整理成一个扁平的对象，fieldErrors 按字段名列出每个字段的错误信息数组。一个字段可能同时有好几条错误，比如空内容会同时违反 min(1) 和 min(5)，数组里就有两条，页面上显示第一条就行。
注意：检查通过以后，只用 result.data，不要再用原始的 formData。result.data 里只有规则书里写了的字段，而且是清理过的。
{ error: '...' }，不再用 message、invalid_type_error、required_error；整理错误用 z.flattenError(error)，不再用 error.flatten() 或 error.format()。让 Claude 写 Zod 代码时，提醒它你用的是 Zod 4。昨天的 action 做完就结束了，不返回任何东西。要让粉丝看到“哪里要改”或“收到了”，action 得返回一个结果，页面还得能接住这个结果并显示出来。React 提供的 useActionState 就是干这个的：
const [state, formAction, pending] = useActionState(submitQuestion, initialState)它接收两个参数：你的 Server Action 和一个初始状态；返回三样东西：
state：action 最近一次返回的结果，第一次渲染时是初始状态。formAction：一个包装过的 action，交给 <form action={formAction}>。pending：action 是否正在运行，true 表示“提交中”。用了 useActionState，Server Action 的参数会多一个：第一个参数是上一次的状态，第二个才是 FormData，返回值就是新的状态。
export async function submitQuestion(prevState: AskState, formData: FormData): Promise<AskState>状态长什么样由你定。提问箱需要四样信息：成功没有、一句总的提示、每个字段的错误、粉丝原来写的内容：
dongge-web/lib/question-schema.ts（接在上面的代码后面）
export type AskState = {
ok: boolean
message: string
errors?: {
content?: string[]
nickname?: string[]
}
values?: {
content: string
nickname: string
}
}为什么这个类型不放在 actions.ts 里？因为 'use server' 文件只能导出 async 函数，而表单组件要用这个类型定义初始状态。类型本身可以导出，但把规则书和状态类型放在一起，找起来更方便。
useActionState 是 Hook，所以用它的表单必须是客户端组件。做法和 DAY 39 一样：页面留在服务端负责查数据库，把表单拆成一个单独的 QuestionForm 客户端组件。
拿到 state 后，在输入框下面显示对应的错误：
{state.errors?.content && (
<p id="content-error" className="mt-1 text-sm text-red-600">
{state.errors.content[0]}
</p>
)}?. 是可选链：errors 不存在时不会报错，直接得到 undefined，整段就不显示。输入框上再加 aria-invalid 和 aria-describedby="content-error"，读屏软件会把错误和输入框关联起来念给视障用户听。总提示放在一个带 aria-live="polite" 的段落里，内容一变，读屏软件就会念出来。
还有一个很容易忽略的细节：React 在表单 action 运行完后，会自动清空表单里的输入框。提交成功时这正是我们想要的；但校验失败时，粉丝认真写了一大段，只是超了几个字，结果全被清空，体验很糟。所以校验失败时，action 把原始内容放进 values 一起返回，输入框用 defaultValue={state.values?.content} 显示它。成功时不返回 values，输入框自然就空了。
网速慢的时候，粉丝点了提交没反应，很可能再点一下、两下，结果同一个问题存了三遍。分两层防：
pending 在提交期间禁用按钮，文字换成“正在投递…”。<button disabled={pending}> 一行就够。这能挡住绝大多数手抖的连点。服务器上的检查只挡“同一个问题重复投递”。如果有人用脚本每秒提交一百个不同的问题，这一招就不够了，那需要“限流”，DAY 67 安全加固时再做。今天把正常使用中最常见的问题解决掉就好。
第一，为什么不直接写 formData.get('content') as string？你在网上的教程里会经常看到这种写法，连一些官方示例都这么写。as string 叫类型断言，意思是“TypeScript 你别管了，我保证它是字符串”。但它只是让编辑器不再报错，运行时什么都没检查：如果请求里根本没有这个字段，值其实是 null，后面调用 .trim() 就会让程序崩掉。Zod 不一样，它在运行时真的去看这个值是什么，不是字符串就返回错误。类型断言是对编辑器的承诺，校验才是对数据的检查。凡是来自外部的数据，都应该校验，而不是断言。
第二，“200 个字”到底怎么算？Zod 的 min、max 和浏览器的 maxLength 用的都是 JavaScript 字符串的 length。一个汉字算 1，一个英文字母算 1，但很多表情符号算 2，甚至更多。所以一个粉丝写了 195 个字加 3 个表情，可能会被提示超长。对提问箱来说这无伤大雅，把上限定得宽松一点就好；只要记住，前端的 maxLength 和服务器的 max 最好写同一个数字，否则会出现“浏览器让打、服务器不让存”的尴尬。
另外，你可能会想：同一份规则书能不能也在浏览器里用，在粉丝点提交前就先检查一遍？可以，Zod 在浏览器里也能运行。但那样表单组件的代码会复杂不少，而浏览器自带的 required、maxLength 已经覆盖了最常见的情况。现阶段保持简单：浏览器做粗检查，服务器做精检查。
到这里，一个表单该有的样子你就都见过了：浏览器先做一遍快速检查；服务器用规则书做真正的检查；结果带着具体提示回到页面；提交过程中按钮不能再点；重复的请求不会重复写入。以后后台的每一个表单，都照这个套路来。
安装 Zod，确认是 4.x
cd ~/code/dongge-web
npm install zod
npm ls zodnpm ls zod 显示的版本以 4. 开头。以官方文档为准，如果以后出了新的大版本，写法可能有变化。写规则书（你来写）
新建 lib/question-schema.ts，写入上午第 2 节的 questionSchema、QuestionInput 和第 4 节的 AskState。规则的细节你可以自己定，比如问题最少几个字、最多几个字，但要和页面上 maxLength 的数字保持一致。
先在终端里试一试规则书
新建一个临时文件，看看 Zod 对不同输入的反应：
dongge-web/scripts/zod-try.ts
import * as z from 'zod'
import { questionSchema } from '../lib/question-schema'
const samples = [
{ content: ' ', nickname: '' },
{ content: '你好', nickname: null },
{ content: ' 打斯诺克前你会先做什么？ ', nickname: ' 小鹿 ' },
]
for (const sample of samples) {
const result = questionSchema.safeParse(sample)
if (result.success) {
console.log('通过：', result.data)
} else {
console.log('不通过：', z.flattenError(result.error).fieldErrors)
}
}npx tsx scripts/zod-try.tsrm scripts/zod-try.ts。改写 Server Action（核心逻辑你来写）
把 app/ask/actions.ts 改成下面的样子。其中“一分钟内重复”的那段查询是今天的核心逻辑，先自己写，写完再对照：
dongge-web/app/ask/actions.ts
'use server'
import { revalidatePath } from 'next/cache'
import * as z from 'zod'
import prisma from '@/lib/prisma'
import { questionSchema, type AskState } from '@/lib/question-schema'
export async function submitQuestion(
prevState: AskState,
formData: FormData,
): Promise<AskState> {
const raw = {
content: formData.get('content'),
nickname: formData.get('nickname'),
}
const result = questionSchema.safeParse(raw)
if (!result.success) {
return {
ok: false,
message: '有几处需要改一下。',
errors: z.flattenError(result.error).fieldErrors,
values: {
content: typeof raw.content === 'string' ? raw.content : '',
nickname: typeof raw.nickname === 'string' ? raw.nickname : '',
},
}
}
const { content, nickname } = result.data
// 一分钟内内容完全相同的提问，不再重复写入
const oneMinuteAgo = new Date(Date.now() - 60 * 1000)
const duplicate = await prisma.question.findFirst({
where: { content, createdAt: { gte: oneMinuteAgo } },
select: { id: true },
})
if (!duplicate) {
await prisma.question.create({ data: { content, nickname } })
revalidatePath('/ask')
}
return { ok: true, message: '收到了。东哥看过之后，会挑一些在下面回答。' }
}几个要读懂的点：raw 里是原始值，只用来校验和在失败时回填；写数据库只用 result.data。createdAt: { gte: oneMinuteAgo } 是 Prisma 的比较写法，gte 是“大于等于”，相当于 SQL 的 created_at >= ...。findFirst 找到第一条符合条件的就返回，找不到返回 null。prevState 这次没用上，但它必须留在第一个位置，因为 useActionState 会把上一次的状态传进来。
拆出表单组件（样板交给 Claude）
发送 claude 部分的第一条提示词，让 Claude 把昨天页面里的表单改写成客户端组件。拿到后和下面对照，逐行读懂：
dongge-web/components/QuestionForm.tsx
'use client'
import { useActionState } from 'react'
import { submitQuestion } from '@/app/ask/actions'
import type { AskState } from '@/lib/question-schema'
const initialState: AskState = { ok: false, message: '' }
export default function QuestionForm() {
const [state, formAction, pending] = useActionState(submitQuestion, initialState)
return (
<form action={formAction} className="space-y-4 rounded-2xl border p-6">
<div>
<label htmlFor="content" className="block text-sm font-medium">
你的问题
</label>
<textarea
id="content"
name="content"
rows={4}
required
maxLength={200}
defaultValue={state.values?.content}
aria-invalid={Boolean(state.errors?.content)}
aria-describedby="content-error"
placeholder="比如：打斯诺克前你会做什么准备？"
className="mt-1 w-full rounded-lg border p-3"
/>
{state.errors?.content && (
<p id="content-error" className="mt-1 text-sm text-red-600">
{state.errors.content[0]}
</p>
)}
</div>
<div>
<label htmlFor="nickname" className="block text-sm font-medium">
昵称（可以不填）
</label>
<input
id="nickname"
name="nickname"
maxLength={20}
defaultValue={state.values?.nickname}
aria-invalid={Boolean(state.errors?.nickname)}
aria-describedby="nickname-error"
className="mt-1 w-full rounded-lg border p-3"
/>
{state.errors?.nickname && (
<p id="nickname-error" className="mt-1 text-sm text-red-600">
{state.errors.nickname[0]}
</p>
)}
</div>
<button
type="submit"
disabled={pending}
className="rounded-full bg-black px-6 py-2 text-white disabled:opacity-50"
>
{pending ? '正在投递…' : '投进提问箱'}
</button>
<p aria-live="polite" className={state.ok ? 'text-sm text-green-700' : 'text-sm text-red-600'}>
{state.message}
</p>
</form>
)
}读的时候重点看三处：useActionState 返回的三样东西分别用在哪；每个 defaultValue 和错误提示从 state 的哪里来；disabled:opacity-50 是 Tailwind 的状态前缀，按钮被禁用时半透明。
页面换上新表单
打开 app/ask/page.tsx：删掉整个 <form>...</form>，换成 <QuestionForm />；删掉 import { submitQuestion } from './actions'，加上 import QuestionForm from '@/components/QuestionForm'。页面里的两个数据库查询不动。
逐个测试校验规则
用开发者工具的 Elements 面板删掉 required 和 maxLength 属性，模拟绕过浏览器检查的请求，然后逐条测试，每条都要看页面提示和数据库：
| 输入 | 应该看到 |
|---|---|
| 问题只有空格 | 问题下面：请先写下你的问题。 |
| 问题“你好” | 问题至少写 5 个字，输入框里仍然是“你好” |
| 问题超过 200 字 | 问题最多 200 个字，写的内容没有被清空 |
| 昵称超过 20 字 | 昵称下面：昵称最多 20 个字 |
| 正常的问题，昵称只打空格 | 绿色提示，数据库里 nickname 是 null |
测试防连点和防重复
在开发者工具的 Network 面板把网速调成 Slow 4G，提交一条问题，观察按钮在提交期间变成半透明的“正在投递…”，点不动。然后把网速调回 No throttling，把同一个问题原样再提交一次。
让 Claude 审查，然后提交
发送 claude 部分的第二条提示词，看看它能不能找出你没想到的边界情况，觉得有道理的自己改。然后：
npm run lint
npm run build
git add .
git commit -m "提问箱：Zod 校验、错误提示、防重复提交"
git pushuseActionState 的参数类型不匹配：Server Action 的参数顺序不对。用了 useActionState，第一个参数必须是上一次的状态，第二个才是 formData，返回值类型要和初始状态的类型一致。invalid_type_error、message 或 error.flatten()，提示没生效或被标成已弃用：那是 Zod 3 的写法。Zod 4 里用 { error: '...' } 和 z.flattenError(error)。values，输入框写的是 defaultValue={state.values?.content}，而不是 value=。useActionState：表单组件第一行没写 'use client'，或者你把 Hook 直接写进了 page.tsx。把表单拆成单独的客户端组件。actions.ts 导出 initialState 常量时报错：'use server' 文件只能导出 async 函数。把初始状态定义在表单组件里，类型放在 lib/question-schema.ts。只在前端校验为什么不够？
前端校验运行在访客的浏览器里，访客可以用开发者工具删掉 required、maxLength，也可以完全不经过页面，直接用工具向 Server Action 发请求，内容想填什么就填什么。服务器收到的请求不一定来自你的页面，所以必须在服务器上用同一套规则再检查一遍，这才是真正的防线。前端校验的作用是让正常访客更快看到提示，体验更好。
Zod 的 safeParse 和 parse 有什么区别？Server Action 里为什么用 safeParse？检查通过后为什么要用 result.data，而不是原来的 formData？
parse 不通过时直接抛出错误，safeParse 不会抛错，而是返回一个带 success 的对象，不通过时从 error 里拿到具体原因。Server Action 里要把错误整理成提示返回给粉丝，所以用 safeParse。result.data 是清理过的数据：去掉了首尾空格、做过 transform，而且只包含规则书里定义的字段，原始 formData 里可能还有别人塞进来的其他字段。
按钮在提交时禁用了，为什么服务器上还要做“一分钟内重复”的检查？这个检查能防住什么，防不住什么？
按钮禁用只影响你的页面，脚本或者直接发请求的人不受影响，网络重试也可能让同一请求到达两次。服务器上的检查能防住同一个问题在短时间内被重复写入。它防不住有人用脚本大量提交内容不同的问题，那需要按来源限制提交频率，也就是 DAY 67 要做的限流。
.env.example，知道 Vercel 的环境变量怎么设。NEXT_PUBLIC_ 前缀的含义，并用 server-only 保证数据库代码不会被打包进浏览器。这几天你的 .env 里有了第一个真正的秘密：DATABASE_URL。接下来还会有更多：DAY 46 登录要用的 BETTER_AUTH_SECRET，DAY 49 上传图片要用的 BLOB_READ_WRITE_TOKEN，DAY 55 调用 Claude 要用的 ANTHROPIC_API_KEY。它们的共同点是：谁拿到它，谁就能以你的身份做事。拿到数据库地址的人可以读、改、删你所有的数据；拿到 API Key 的人可以用你的账户花钱。
所以密钥要遵守三条规矩：
.env 里，代码里只写变量名。代码里用 process.env.DATABASE_URL 读取，而不是把那串地址直接写进 .ts 文件。.gitignore 里的 .env* 已经帮你挡住了。但要小心：一旦某次提交里带了密钥，就算下一次提交删掉，它仍然留在 Git 历史里，推到 GitHub 后就等于公开了。*** 再发。截图时也注意别把 .env 拍进去。万一泄露了，删掉提交是不够的，正确的做法是换钥匙：去 Neon 给数据库角色重置密码，拿到新的连接字符串，更新 .env，旧密码立刻作废。这就像丢了家门钥匙，要做的是换锁，而不是祈祷捡到的人不来。
还有一个问题：.env 不提交，那换一台电脑、或者半年后的你，怎么知道项目需要哪些变量？惯例是写一个 .env.example：只列变量名和格式说明，不写真实的值，提交到 Git。别人拿到项目，复制一份改名为 .env，填上自己的值就能跑。因为 .gitignore 里的 .env* 也会匹配到 .env.example，所以要在它下面加一行 !.env.example，开头的感叹号表示“这个例外，不要忽略”。
Next.js 读 .env 时有一条重要规则：普通的环境变量只在服务器上可用；只有名字以 NEXT_PUBLIC_ 开头的变量，才会在构建时被直接写进发给浏览器的 JavaScript 里。所以 process.env.DATABASE_URL 在服务端组件和 Server Action 里能读到，在客户端组件里读到的是空的。
这个设计很安全，但也埋了一个坑：有人为了让客户端组件“也能用”，把变量改名成 NEXT_PUBLIC_DATABASE_URL。这样确实能用了，代价是数据库密码被写进了每个访客下载的 JavaScript 文件里，谁都能在开发者工具里翻出来。记住：NEXT_PUBLIC_ 的意思就是“公开给全世界”，只有本来就可以公开的东西，比如网站的公开网址，才能用这个前缀。你的课程里约定的五个变量，没有一个需要这个前缀。
DAY 39 讲过，客户端组件导入的东西都会被打包进浏览器。如果哪天你或者 Claude 不小心在客户端组件里 import prisma from '@/lib/prisma'，数据库相关的代码就会被尝试打包进浏览器。为了让这种错误在构建时就被发现，在 lib/prisma.ts 第一行加上：
dongge-web/lib/prisma.ts（第一行）
import 'server-only'这一行本身什么都不做，它是一个标记：只要有客户端组件直接或间接导入了这个文件，npm run build 和开发服务器都会报错，告诉你“这个模块只能在服务器上用”。相当于在后厨门口挂一块“闲人免进”的牌子，而且真的有人拦。注意种子脚本 prisma/seed.ts 是自己创建的 Client，没有导入 lib/prisma.ts，所以不受影响。
.env 只在你的电脑上。网站部署到 Vercel 后，Vercel 的服务器上没有这个文件，要在 Vercel 的项目设置里单独填：打开项目，进入 Settings，找到 Environment Variables，填入名字和值，选择它用在哪些环境：
main 分支后部署出来的那个。vercel env pull 命令把它下载到本地。两个要点：Vercel 会加密保存这些值；改了环境变量之后，已经部署的版本不会自动更新，要重新部署一次才生效。很多“本地好好的，线上连不上数据库”的问题，都是忘了在 Vercel 上填变量，或者填了没重新部署。DAY 54 上线时你会真正在这里填 DATABASE_URL，今天先认识这个页面。
XSS（跨站脚本攻击）的意思是：攻击者想办法让自己写的 JavaScript 在别的访客的浏览器里、以你的网站的身份运行。
拿提问箱举例。有人提交了这样一个“问题”：
<img src="x" onerror="alert('XSS')">这是一张地址无效的图片，加载失败时会运行 onerror 里的代码。如果你的页面把问题内容当作 HTML 插进页面，比如 DAY 19 学过的 element.innerHTML = question.content，那么每个打开提问箱的人，浏览器都会运行这段代码。示例里只是弹个窗，真正的攻击者会写别的：偷走你登录后台后的会话信息、冒充你执行操作、把访客引到钓鱼网站。等 DAY 46 你有了管理员登录，这就不是小事了。
React 默认挡住了最常见的这一种。你在 JSX 里写 {question.content}，React 会把内容当作纯文字显示，< 会被转成 <，浏览器看到的是字符而不是标签。所以上面那个“问题”在你的页面上只会原样显示成一行代码文字，什么都不会发生。
React 挡不住的，是你主动绕开它的地方，需要自己注意：
dangerouslySetInnerHTML：React 提供的“直接插入 HTML”的属性，名字里就写着危险。永远不要把用户写的内容交给它。以后如果想支持粉丝提问里的换行或加粗，用 CSS 的 whitespace-pre-line 这类办法，而不是插入 HTML。<a href={用户填的地址}> 可能被填成 javascript: 开头的地址，点一下就运行代码。新版 React 会拦截这类地址，但别依赖它，自己用 Zod 校验只接受 https:// 开头的网址。CSRF（跨站请求伪造）换了一个思路：攻击者不需要在你的网站上运行代码，而是在他自己的网站上放一个隐藏的表单，目标指向你的网站。如果你登录了官网后台，又在同一个浏览器里打开了他的页面，这个表单悄悄自动提交，浏览器会照常带上你的登录凭证（Cookie），你的网站以为是你本人在操作，比如“删除所有穿搭”。就像有人拿着一张你签过名的空白支票去银行。
Next.js 和现代浏览器默认挡住了大部分：
Origin（请求从哪个网站发出）和 Host（请求发到哪个网站）。从别人的网站发来的请求，两者对不上，Next.js 直接拒绝执行 action。还需要你自己注意的：第一，不要用 GET 请求修改数据，比如写一个 /api/delete-look?id=3 的 GET 接口，这种接口一张图片就能触发。第二，Origin 检查只有 Server Action 自动做，如果以后你写了接收 POST 的 Route Handler 并且依赖登录状态，需要自己考虑这个问题，能用 Server Action 就用 Server Action。第三，这个检查防的是“借用浏览器”，不是“只有我的页面能调用”：用工具直接发请求的人不会带 Origin 头，Next.js 会放行。所以输入校验和登录检查一样都不能省，下午的挑战实验会让你亲眼看到这一点。
SQL 注入发生在“把用户输入直接拼进 SQL 字符串”的时候。假设有人这样写查询：
// 危险的写法，只用来理解原理，不要写进项目
const sql = "SELECT * FROM questions WHERE nickname = '" + nickname + "'"正常情况下 nickname 是“小鹿”，拼出来的 SQL 没问题。但如果有人把昵称填成 ' OR '1'='1，拼出来就变成了 WHERE nickname = '' OR '1'='1'，条件永远成立，所有提问（包括待审核和隐藏的）都被查了出来。填得更狠一点，还可能拼出删除数据的语句。问题的根源是：数据和命令混在了同一个字符串里，数据库分不清哪部分是你写的命令、哪部分是用户填的内容。
Prisma 默认挡住了它。你写的 prisma.question.create({ data: { content } })、findMany({ where: { nickname } })，Prisma 生成的是“参数化查询”：SQL 语句和数据分开发给数据库，数据库明确知道哪部分是数据，不管数据里写了什么引号、分号，都只当作普通文字存起来。这是用 ORM 的一大好处。
还需要注意的：Prisma 也允许你直接写 SQL。$queryRaw 要用反引号的模板写法，把变量放在 ${} 里，Prisma 会自动参数化，是安全的；名字里带 Unsafe 的 $queryRawUnsafe 和 $executeRawUnsafe 接受你自己拼好的字符串，一旦拼进用户输入就会重新打开注入的口子。DAY 61 你会写 SQL 做统计，到时候只用 $queryRaw 的模板写法，永远不用 Unsafe 版本拼接用户输入。
三种攻击看下来，背后是同一个原则：从浏览器来的一切都可能被改过，服务器只相信自己决定的东西。落到提问箱上，有几条具体的做法：
prisma.question.create({ data: Object.fromEntries(formData) })，把表单里的所有字段一股脑存进去。攻击者只要在请求里多加两个字段 status=APPROVED 和 answer=...，就能跳过审核，还能伪造一条“东哥的回答”。你的代码只从 Zod 校验后的 result.data 里取 content 和 nickname，Zod 默认会丢掉规则书里没写的字段，所以这招对你无效。console.error 记下来给自己看，给访客一句友好的提示。还有一类问题今天不解决，但要心里有数：有人用脚本每秒提交成百上千条问题，把提问箱塞满。这需要“限流”，DAY 67 再做。安全不是一次做完的事，而是每加一个功能，都用今天这几个角度过一遍。
检查密钥有没有进过 Git
cd ~/code/dongge-web
git ls-files | grep -i env
git log -p --all | grep -c "neon.tech"0。如果第二条不是 0，说明数据库地址曾经被提交过：去 Neon 控制台的 Roles 页面给这个角色重置密码，把新的连接字符串换进 .env，再继续。写 .env.example
新建 .env.example，只写变量名和格式，不写真实的值。后面几天要用的变量先以注释的形式列出来：
dongge-web/.env.example
# 复制本文件为 .env，填入真实的值。本文件会提交到 Git，不要写真实的密钥。
# Neon 数据库的直连地址（Connect 窗口里关掉 Connection pooling 后复制）
DATABASE_URL="postgresql://用户名:密码@主机/neondb?sslmode=require"
# DAY 46 起：Better Auth
# BETTER_AUTH_SECRET=""
# BETTER_AUTH_URL="http://localhost:3000"
# DAY 49 起：Vercel Blob
# BLOB_READ_WRITE_TOKEN=""
# DAY 55 起：Claude API
# ANTHROPIC_API_KEY=""然后打开 .gitignore，在 .env* 那一行的下面加一行：
!.env.examplegit status 里出现 .env.example，但仍然没有 .env。给 lib/prisma.ts 加上 server-only，并做个实验
npm install server-only在 lib/prisma.ts 的第一行加上 import 'server-only'。然后做个实验：打开客户端组件 components/Quiz.tsx，在导入区临时加一行 import prisma from '@/lib/prisma'，保存后看浏览器和终端。
看一眼 Vercel 的环境变量页面
登录 Vercel，打开 DAY 36 部署的 dongge-react 项目，进入 Settings 里的 Environment Variables 页面，看看 Production、Preview、Development 三个选项在哪。今天只看，不要添加。dongge-web 会在 DAY 54 部署，到时候在它的项目里填 DATABASE_URL。
XSS 实验
在提问箱提交这样一个问题：<img src="x" onerror="alert('XSS')">。它现在是待审核，前台看不到。运行 npx prisma studio，找到这一行，把 status 改成 APPROVED，answer 随便填一句，保存。刷新 /ask。
onerror，会看到前面的尖括号被转成了 <。这就是 React 的默认转义。做完在 Prisma Studio 里把这一行的 status 改成 HIDDEN。
SQL 注入实验
提交一个问题：'); DROP TABLE questions; --，昵称填 ' OR '1'='1。
questions 表安然无恙。挑战（可选）：亲眼看看 CSRF 检查
先用一段英文内容提交一个问题，比如 csrf test one，方便后面在命令里找到它。在开发者工具的 Network 面板里找到这次 POST 请求，右键选 Copy，再选 Copy as cURL，把复制的命令粘贴到 VS Code 的一个新文件里。
第一次修改：把 csrf test one 改成 csrf test two，把 origin: http://localhost:3000 改成 origin: https://evil.example，整段复制到终端运行。
npm run dev 的那个终端里打印出一行错误，结尾是 Aborting the action.，数据库里没有 csrf test two。这就是 Next.js 在拦截“从别的网站发来的请求”。第二次修改：把内容改成 csrf test three，把带 origin 的那一整行 -H '...' 删掉，再运行。
csrf test three。没有 Origin 头的请求不是浏览器发的，不存在“借用你的登录状态”的问题，所以 Next.js 放行。这正说明 CSRF 检查不等于“只有我的页面能调用”，Zod 校验和以后的登录检查一样都不能少。做完把这几条测试提问在 Prisma Studio 里改成 HIDDEN。
让 Claude 扮演攻击者
发送 claude 部分的第一条提示词。它只会讲问题和原理，不会给代码、不会改文件。把它列出的问题抄到笔记里，每条标上“已被默认挡住”“需要我修”“以后再做（DAY 67 限流）”。一般至少会有下面三条需要你修，没提到的你也自己加上。
自己修：昵称不许冒充东哥
在 lib/question-schema.ts 里给 nickname 加一条规则：去掉空格后如果包含“东哥”两个字，就报错。先自己写，写完对照：
nickname: z
.string()
.trim()
.max(20, '昵称最多 20 个字。')
.refine((value) => !value.includes('东哥'), { error: '昵称里请不要用“东哥”。' })
.nullish()
.transform((value) => value || null),refine 用来写 Zod 没有内置的自定义规则：传入一个函数，返回 true 表示通过，false 表示不通过，第二个参数是不通过时的提示。
自己修：数据库出错时给友好提示
在 app/ask/actions.ts 里，用 try...catch 包住“查重复 + 写入 + revalidatePath”这一段：出错时用 console.error 在服务器上记下完整错误，返回 ok: false、一句友好的提示，并用 values 回填粉丝写的内容。写完对照：
const { content, nickname } = result.data
try {
const oneMinuteAgo = new Date(Date.now() - 60 * 1000)
const duplicate = await prisma.question.findFirst({
where: { content, createdAt: { gte: oneMinuteAgo } },
select: { id: true },
})
if (!duplicate) {
await prisma.question.create({ data: { content, nickname } })
revalidatePath('/ask')
}
} catch (error) {
console.error('提问写入失败', error)
return {
ok: false,
message: '提问箱暂时打不开，请过一会儿再试。',
values: { content, nickname: nickname ?? '' },
}
}
return { ok: true, message: '收到了。东哥看过之后，会挑一些在下面回答。' }以后如果 action 里用了 redirect()，不要把它放进 try 里，它是靠抛出一个特殊的“错误”来实现跳转的，会被 catch 误吞掉。
.env 里的密码改错一个字母，重启 npm run dev，提交问题，页面显示“提问箱暂时打不开”，终端里有详细的错误；改回正确的密码，重启，一切恢复。请 Claude 复查，然后提交
用 claude 部分的第二条提示词让 Claude 复查，它说没修好的地方，自己再改。最后：
npm run lint
npm run build
git add .
git commit -m "安全基础：server-only、.env.example、昵称规则、错误处理"
git pushprocess.env.DATABASE_URL 得到 undefined：这是故意的设计，普通环境变量只在服务器上可用。把用到它的逻辑移到服务端组件或 Server Action 里，千万不要改名加 NEXT_PUBLIC_。!.env.example 之后 .env.example 还是没出现在 git status 里：检查这一行是不是写在 .env* 的下面，顺序反了不生效；文件名是否正好是 .env.example。.env 但网站还在用旧值：环境变量在开发服务器启动时读取，改完要按 Ctrl + C 停掉 npm run dev 再重新启动。Vercel 上同理，改完要重新部署。lib/prisma.ts 后报 server-only 相关的错：server-only 只允许在 Next.js 的服务端环境里导入。独立运行的脚本要像 prisma/seed.ts 那样自己创建 Prisma Client。curl 开头。这个挑战不影响后面的课程，做不出来可以跳过。XSS 是怎么发生的？React 默认帮你挡住了哪一部分？
XSS 是攻击者把一段 JavaScript 伪装成普通内容提交上来（比如在提问里写一个带 onerror 的图片标签），如果网站把这段内容当作 HTML 插进页面，其他访客打开页面时，浏览器就会以你网站的身份运行它，可能偷走登录信息、冒充用户操作。React 默认会把 {} 里的内容当作纯文字显示，尖括号被转义，所以用 JSX 正常显示用户内容时，脚本不会运行。React 挡不住的是你主动绕开它的地方：dangerouslySetInnerHTML、把用户填的地址直接放进 href、来路不明的第三方脚本，这些要自己把关。
为什么绝不能把数据库地址放进 NEXT_PUBLIC_ 开头的变量？import 'server-only' 又防的是什么？
NEXT_PUBLIC_ 开头的变量会在构建时被直接写进发给浏览器的 JavaScript，任何访客都能在开发者工具里看到，等于把数据库密码公开。server-only 防的是另一种意外：客户端组件导入了只该在服务器上运行的模块（比如 lib/prisma.ts），它会让这种导入在构建时就报错，而不是等到上线才发现问题。
Prisma 默认挡住了 SQL 注入，什么情况下你仍然可能写出有注入漏洞的代码？
当你绕过 Prisma 的普通查询、自己拼 SQL 字符串的时候，特别是用 $queryRawUnsafe 或 $executeRawUnsafe，并且把用户输入用加号或模板字符串拼进去。安全的做法是用 $queryRaw 的反引号模板写法，把变量放在 ${} 里，由 Prisma 参数化；或者干脆用 findMany 这类普通查询。
昨天你让 Claude 扮演攻击者检查了提问箱，学会了密钥放 .env、防 XSS 和 CSRF。到今天为止，dongge-web 的所有页面都是公开的：谁打开网址都能看。这对前台没问题，粉丝本来就该看到你的三个世界。
但接下来几天你要做后台：新建 look、上传照片、审核粉丝提问。这些操作只能你自己做。如果后台谁都能进，路人就能删掉你的 look，或者把一条恶意提问设成“已通过”挂在首页上。
打个比方：你的拳馆前厅谁都能进来看训练，但器材室和更衣柜只有会员才能开。网站也一样，要先有一道“门禁”，确认来的人是你，才让他进后台。这道门禁就是登录系统。
登录系统看起来只是一个输入框加一个按钮，背后要处理的事情很多：密码怎么存、登录状态怎么保持、怎么退出、怎么防止别人猜密码。这些事自己从零写，很容易留下安全漏洞。所以我们用一个成熟的库 Better Auth 来处理，你负责把它接进项目，并且弄懂每一块在做什么。
这两个词经常被混着说，其实回答的是两个问题。
认证（Authentication）回答“你是谁”。你在登录页输入邮箱和密码，系统核对无误，就确认了“这个人是东哥”。就像拳馆前台看你的会员卡，确认你是本人。
授权（Authorization）回答“你能做什么”。确认了你是谁之后，还要判断你有没有权限做某件事。会员能进更衣室，但只有教练能进教练办公室。同样是持卡人，能去的地方不一样。
在 dongge-web 里，这两件事分别是：
ADMIN_EMAIL 的那个人才算管理员。这部分明天由你自己写。网络上还有两个和它们对应的状态码，你以后在日志里会看到：401 表示“没认证，不知道你是谁”，403 表示“知道你是谁，但你没这个权限”。
HTTP 协议有个特点：每一次请求都是独立的，服务器不会自动记得上一次请求是谁发的。你登录成功后点开下一个页面，服务器怎么知道还是你？
想象去商场存包：你把包交给柜台，柜台在本子上记一行“3 号柜，某某的包”，然后给你一个写着 3 号的号牌。之后你每次来取东西，只要出示号牌，柜台对一下本子就知道是你。
整个过程是这样的：你提交邮箱和密码，服务器核对成功，在 session 表新增一行，同时在响应里设置一个名叫 better-auth.session_token 的 Cookie。之后你访问任何页面，浏览器自动带上这个 Cookie，服务器拿里面的令牌去 session 表查，查到了就知道是你。退出登录时，服务器删掉 session 表里那一行，并让浏览器清掉 Cookie，号牌就作废了。
Better Auth 设置的 Cookie 带有几个安全属性，你在开发者工具里能看到：
HttpOnly：页面上的 JavaScript 读不到它。就算网站被注入了恶意脚本（DAY 45 讲的 XSS），也偷不走令牌。Secure：只通过 HTTPS 发送。本地开发用的是 http，所以本地看不到这个属性，上线后才有。SameSite=Lax：别的网站发起的跨站请求一般不会带上它，这是防 CSRF 的一层保护。“明文存储”就是数据库里直接存着 mypassword123 这样的原文。这样做的风险是：一旦数据库泄露（被黑、误把备份传到网上、某个员工拷走），所有人的密码都直接暴露。很多人在不同网站用同一个密码，一个网站泄露，他的邮箱、社交账号可能都跟着出事。
正确的做法是存哈希值。哈希函数像一台绞肉机：把密码放进去，出来一串固定长度、看起来乱七八糟的字符。它有三个特点：
光有哈希还不够。攻击者可以提前把常见密码的哈希算好做成一张表，拿去对照。所以好的做法还会给每个密码加一段随机的“盐”（salt），让相同的密码算出不同的结果；并且故意用一个很慢的算法，让攻击者每猜一次都要花不少计算时间。Better Auth 默认使用的 scrypt 就是这样一种加了盐、故意算得慢的算法。你不需要自己实现它，但要知道数据库里存的那串字符是什么，以及为什么它不怕被看到。
还有一个细节：登录失败时，提示语只说“邮箱或密码不对”，不要分别提示“邮箱不存在”或“密码错误”。否则攻击者可以先用这个提示试出哪个邮箱是真的管理员邮箱，再专门去猜它的密码。
Better Auth 是一个 TypeScript 写的认证库，能和 Next.js、Prisma 直接配合。接入它，你要写四块东西，每块各管一件事。
第一块：服务端配置，告诉 Better Auth 用哪个数据库、开启哪种登录方式。
dongge-web/lib/auth.ts
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import prisma from "@/lib/prisma";
export const auth = betterAuth({
database: prismaAdapter(prisma, {
provider: "postgresql",
}),
emailAndPassword: {
enabled: true,
disableSignUp: true,
},
});逐行看：第 1 行导入创建认证实例的函数。第 2 行导入 Prisma 适配器，它让 Better Auth 通过你 DAY 42 建好的 Prisma Client 读写数据库。第 3 行导入 DAY 42 写的 lib/prisma.ts：那个文件最后一行是 export default prisma（默认导出），所以导入时不加花括号。provider: "postgresql" 说明数据库是 PostgreSQL（Neon）。emailAndPassword.enabled 开启邮箱密码登录。disableSignUp: true 关闭注册，这一行是今天的安全重点，第 6 节细讲。
你可能注意到这里没写密钥。Better Auth 会自动读取环境变量 BETTER_AUTH_SECRET（用来给令牌签名）和 BETTER_AUTH_URL（网站地址），所以只要放进 .env 就行。
第二块：接口入口。登录、退出、查询会话这些请求都要有一个地址来接收。
dongge-web/app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { GET, POST } = toNextJsHandler(auth);文件夹名 [...all] 是 DAY 38 学过的动态路由的一种，叫“捕获所有”：/api/auth/sign-in/email、/api/auth/get-session 这些地址都会进到这个文件。toNextJsHandler 把 Better Auth 包装成 Next.js 认识的 GET 和 POST 处理函数，这种文件就是 DAY 43 提过的 Route Handler。
第三块：数据库表。Better Auth 需要 4 张表：user 存用户，session 存登录会话，account 存登录方式（邮箱密码登录的密码哈希就存在这里），verification 存验证码一类的临时数据。你不用手写，用它的命令行工具自动加进 schema.prisma，再用 Prisma 迁移。
第四块：浏览器端客户端，给登录表单调用。
dongge-web/lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
export const authClient = createAuthClient();前台和接口在同一个域名下，所以不用传地址。之后在客户端组件里调用 authClient.signIn.email(...) 就能登录，调用 authClient.signOut() 就能退出。
网站只有你一个管理员，所以根本不需要“注册”功能。如果注册开着，任何人都能给自己建个账号，再配合一个没写好的权限检查，就可能混进后台。所以 lib/auth.ts 里写了 disableSignUp: true：网站的注册接口直接拒绝所有人，登录照常可用。
问题来了：注册关了，你自己的账号怎么来？答案是写一个只在你电脑上运行一次的脚本。脚本里单独创建一个“临时开着注册”的 Better Auth 实例，只用它创建一个账号，然后退出。网站用的 lib/auth.ts 始终保持关闭。
dongge-web/scripts/create-admin.ts
import "dotenv/config";
import { createInterface } from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import prisma from "../lib/prisma";
async function main() {
const email = process.env.ADMIN_EMAIL;
if (!email) {
throw new Error("请先在 .env 里设置 ADMIN_EMAIL");
}
const dbHost = new URL(process.env.DATABASE_URL ?? "").host;
const rl = createInterface({ input, output });
console.log(`将在数据库 ${dbHost} 里创建管理员 ${email}`);
const password = await rl.question("请输入管理员密码（至少 12 位）：");
rl.close();
if (password.length < 12) {
throw new Error("密码太短，至少 12 位");
}
// 只在这个脚本里临时开启注册，网站用的 lib/auth.ts 始终关闭注册
const setupAuth = betterAuth({
database: prismaAdapter(prisma, { provider: "postgresql" }),
emailAndPassword: { enabled: true, autoSignIn: false },
});
await setupAuth.api.signUpEmail({
body: { name: "东哥", email, password },
});
console.log("管理员创建成功，可以去 /login 登录了");
}
main()
.catch((error) => {
console.error(error);
process.exitCode = 1;
})
.finally(() => prisma.$disconnect());逐段解释：
import "dotenv/config" 读取 .env，让脚本拿到 DATABASE_URL 和 ADMIN_EMAIL。Next.js 会自动读 .env，但单独运行的脚本不会，所以要手动加。它必须写在最前面，因为下面导入 prisma 时就要用到数据库地址。ADMIN_EMAIL 读，而不是写死在代码里。明天做授权检查时也用同一个变量，两处永远一致。dbHost 只取数据库地址里的主机名打印出来，让你运行前看清楚“要往哪个数据库写”。以后你会有开发库、测试库、正式库，这一行能防止写错地方。readline 让脚本在终端里问你密码。密码不写进任何文件，也不出现在命令里，就不会留在代码仓库或终端历史中。setupAuth 是脚本自己的实例，没有 disableSignUp，所以能注册。autoSignIn: false 表示注册后不自动创建登录会话，脚本不需要登录。setupAuth.api.signUpEmail 是 Better Auth 提供的服务端调用方式，效果和在网页上注册一样：密码会先用 scrypt 算成哈希，再存进 account 表。catch 把错误打印出来，finally 断开数据库连接，让脚本正常结束。登录表单要响应用户输入、显示错误、禁用按钮，这些都是交互，所以写成客户端组件（DAY 39 学的 "use client"）。页面本身留在服务端，只负责排版。
dongge-web/app/login/login-form.tsx
"use client";
import { useState, type FormEvent } from "react";
import { useRouter } from "next/navigation";
import { authClient } from "@/lib/auth-client";
export function LoginForm() {
const router = useRouter();
const [error, setError] = useState("");
const [pending, setPending] = useState(false);
async function handleSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
setError("");
setPending(true);
const formData = new FormData(event.currentTarget);
const result = await authClient.signIn.email({
email: String(formData.get("email") ?? ""),
password: String(formData.get("password") ?? ""),
});
setPending(false);
if (result.error) {
setError("邮箱或密码不对，再试一次。");
return;
}
router.push("/");
router.refresh();
}
return (
<form onSubmit={handleSubmit} className="mt-8 space-y-4">
<div>
<label htmlFor="email" className="block text-sm font-medium">邮箱</label>
<input id="email" name="email" type="email" required autoComplete="email"
className="mt-1 w-full rounded border px-3 py-2" />
</div>
<div>
<label htmlFor="password" className="block text-sm font-medium">密码</label>
<input id="password" name="password" type="password" required autoComplete="current-password"
className="mt-1 w-full rounded border px-3 py-2" />
</div>
{error && <p role="alert" className="text-sm text-red-600">{error}</p>}
<button type="submit" disabled={pending}
className="w-full rounded bg-black px-4 py-2 text-white disabled:opacity-50">
{pending ? "登录中…" : "登录"}
</button>
</form>
);
}重点几行：event.preventDefault() 阻止浏览器默认的整页提交（DAY 21 学过）。new FormData(event.currentTarget) 一次性读出表单里所有带 name 的输入框，要在 await 之前读，因为等待之后 React 事件对象就失效了。authClient.signIn.email 把邮箱密码发到 /api/auth/sign-in/email，返回一个对象，失败时里面有 error。失败提示用的是统一的“邮箱或密码不对”，原因见第 4 节。成功后 router.push("/") 跳回首页，router.refresh() 让服务端组件重新读取一次，拿到最新的登录状态。今天先跳首页，明天做好 /admin 再改成跳后台。
每个输入框都配了 label，并用 htmlFor 和 id 关联（DAY 05 的验收题）。这不只是为了读屏软件，DAY 52 写自动化测试时，测试代码就是靠 label 的文字找到输入框的。
明天你会在这个基础上保护 /admin：没登录或不是管理员，就进不去。
确认起点干净
打开终端进入项目，看一眼 Git 状态。如果有没提交的改动，先提交，这样今天出问题可以随时回退。
cd ~/code/dongge-web
git status今天的分工：lib/auth.ts 里的 disableSignUp 和管理员脚本里的检查由你自己写，登录表单的样式可以交给 Claude 写样板。Claude 每次改完，你都要在 VS Code 的“源代码管理”面板里逐行看一遍改动。
安装 Better Auth
npm install better-auth安装命令以 Better Auth 官方安装文档为准。
package.json 的 dependencies 里出现了 better-auth。生成密钥，写进 .env
先生成一段随机字符串作为签名密钥：
openssl rand -base64 32打开项目根目录的 .env（DAY 42 放 DATABASE_URL 的那个文件），在末尾加三行。把第一行换成刚生成的字符串，第三行换成你自己真实常用的邮箱：
dongge-web/.env
BETTER_AUTH_SECRET=刚才生成的那串字符
BETTER_AUTH_URL=http://localhost:3000
ADMIN_EMAIL=你的邮箱@example.com确认 .env 不会被提交：
git check-ignore -v .env.gitignore 里的规则。如果什么都没输出，说明 .env 没被忽略，先把 .env* 加进 .gitignore 再继续。写服务端配置 lib/auth.ts
新建 lib/auth.ts，内容照第 5 节的代码。emailAndPassword 里的两行自己敲，敲 disableSignUp: true 时想一想：如果漏了这一行，会发生什么？
第 3 行的 import prisma from "@/lib/prisma" 对应 DAY 42 的 lib/prisma.ts，它用的是默认导出，所以不要写成带花括号的 { prisma }。
挂上接口入口，写好浏览器端客户端
新建文件夹和文件 app/api/auth/[...all]/route.ts，内容照第 5 节。注意文件夹名里有方括号和三个点，一个字都不能错。再新建 lib/auth-client.ts，内容也照第 5 节，只有两行有效代码。
生成数据库表并迁移
让 Better Auth 的命令行工具把它需要的 4 个模型写进 prisma/schema.prisma：
npx auth@latest generate它问是否写入 schema 时选是。完成后打开 schema.prisma，你会看到新增的 User、Session、Account、Verification 四个模型。先别急着迁移，逐个看一遍字段，把看不懂的记下来问 Claude。
然后创建迁移并重新生成 Prisma Client：
npx prisma migrate dev --name add-better-auth
npx prisma generateprisma/migrations 里多了一个名字带 add-better-auth 的文件夹；在 Neon 控制台的 Tables 页面能看到 user、session、account、verification 四张新表。写管理员脚本并运行
新建文件夹 scripts，在里面新建 create-admin.ts，内容照第 6 节。main 函数开头的两个检查（没设 ADMIN_EMAIL 就报错、密码少于 12 位就报错）自己敲。然后运行：
npx tsx scripts/create-admin.tstsx 是 DAY 42 跑种子脚本时装的工具，能直接运行 TypeScript 文件。终端会先打印要写入的数据库主机名，确认是你的 Neon 地址后再输入密码。输入的密码会显示在屏幕上，确认身边没人再敲。密码请用一个只在这里用的新密码，至少 12 位，记进你的密码管理器。
SELECT id, email, name FROM "user";
SELECT "providerId", LEFT(password, 20) AS password_head FROM account;写登录页
新建 app/login/login-form.tsx，内容照第 7 节。样式部分可以让 Claude 帮你调，但 handleSubmit 你自己写。再新建页面文件：
dongge-web/app/login/page.tsx
import { LoginForm } from "./login-form";
export const metadata = { title: "管理员登录" };
export default function LoginPage() {
return (
<main className="mx-auto max-w-sm px-4 py-16">
<h1 className="text-2xl font-bold">管理员登录</h1>
<p className="mt-2 text-sm text-neutral-500">这里只给东哥自己用。</p>
<LoginForm />
</main>
);
}试登录
运行 npm run dev，打开 http://localhost:3000/login。先故意输错密码，再输对。
http://localhost:3000/api/auth/get-session，能看到一段 JSON，里面有 session 和 user，user 里是你的邮箱。再打开开发者工具，Application 面板左侧选 Cookies，点 http://localhost:3000，找到 better-auth.session_token，确认 HttpOnly 那一列打了勾。
亲手验证注册已关闭
在登录页按 Cmd + Option + J 打开控制台，粘贴下面这段，模拟一个路人直接调用注册接口：
await fetch("/api/auth/sign-up/email", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name: "路人", email: "someone@example.com", password: "abcd1234efgh" }),
}).then((res) => res.json());SELECT email FROM "user";，仍然只有你一个人。提交
git status
git add -A
git commit -m "接入 Better Auth：管理员登录，关闭公开注册"提交前看一眼 git status 的列表，确认里面没有 .env。DAY 38 说过，dongge-web 要到 DAY 54 才连同数据库一起部署到 Vercel，今天新加的这几个环境变量，到时候会在 Vercel 上另配一套（密钥也会重新生成），现在不用管。
npx auth@latest generate 说找不到配置文件：它默认在 lib/、utils/、项目根目录等位置找 auth.ts。确认文件名和位置对，或者用 npx auth@latest generate --config lib/auth.ts 明确指定。npx prisma generate，或者 VS Code 还没刷新类型。先运行它，再按 Cmd + Shift + P 搜 “TypeScript: Restart TS Server”。BETTER_AUTH_URL 不一致。比如你用的是 127.0.0.1:3000，或者 3000 端口被占用、Next.js 换到了 3001。统一用 http://localhost:3000，改了 .env 要重启 npm run dev。DELETE FROM "user" WHERE email = '你的邮箱';。删之前确认连的是开发库。lib/prisma.ts 里加了 import "server-only"。这个包只能在 Next.js 服务端使用，单独运行的脚本会被它拦住。lib/prisma.ts 不要加它，明天我们只在后台检查的文件里用它。认证和授权有什么区别？密码为什么绝不能明文存储？
认证回答“你是谁”：用邮箱和密码证明你是东哥。授权回答“你能做什么”：已经知道你是谁之后，判断你有没有权限进后台、删 look。可以认证通过但授权失败，比如一个普通账号登录成功，却没有后台权限。密码不能明文存，因为数据库一旦泄露，所有密码原文直接暴露，而很多人多个网站共用密码，损失会扩散。应该存加了盐、用慢速算法（Better Auth 默认 scrypt）算出的哈希值：登录时把输入的密码再算一遍来对比，而从哈希几乎不可能倒推出原文。
浏览器里的 better-auth.session_token 这个 Cookie 存的是什么？它为什么要带 HttpOnly？
存的是会话令牌，相当于存包的号牌。服务器拿它去 session 表查，查到就知道是谁。HttpOnly 让页面上的 JavaScript 读不到它，这样即使页面被注入恶意脚本，脚本也偷不走令牌。但如果有人直接拿到了你电脑上的这个 Cookie，仍然能冒充你，所以它不能外传。
如果把 lib/auth.ts 里的 disableSignUp: true 删掉，会有什么风险？你用什么办法验证它现在确实生效？
删掉后，任何人都可以调用 /api/auth/sign-up/email 给自己注册账号。如果后面的授权检查只判断“有没有登录”，这个人就能进后台。验证方法是在浏览器控制台直接向注册接口发 POST 请求，看到返回的是错误信息，并在数据库里确认 user 表没有新增记录。
requireAdmin()：在服务端读取会话、核对管理员邮箱，不合格就跳转到 /login。middleware.ts 改名成了 proxy.ts，以及为什么它只适合做“乐观跳转”，不算真正的保护。昨天你接好了 Better Auth，能在 /login 登录，浏览器里也拿到了会话 Cookie。但是现在就算有人没登录，只要知道后台网址，照样能打开。因为“能登录”和“页面受保护”是两回事：登录只是发了一张会员卡，还没有人在门口查卡。
今天要做的就是“查卡”，也就是昨天说的授权：每次有人要看后台页面、或者要执行后台操作，都先确认“这个人登录了，而且他就是东哥”。
要查卡，得先想清楚在哪查。一个网站有很多入口：浏览器直接打开页面是一个入口，点按钮触发的 Server Action 是另一个入口。拳馆如果只在大门口查卡，有人从后门、从货梯进来就没人管了。所以原则是：每一个能看到后台数据或改动数据的入口，都要自己查一次。
查卡必须在服务端做。你可能会想：在客户端组件里判断“没登录就不显示后台内容”行不行？不行。客户端代码是发到用户浏览器里运行的，用户可以打开开发者工具随意修改，客户端的判断只能决定“按钮显示不显示”，挡不住人。数据是在服务端查出来的，门禁也必须装在服务端。
Better Auth 在服务端提供了 auth.api.getSession。你把这次请求的请求头交给它，它会从请求头里的 Cookie 取出令牌，去 session 表里查，返回当前用户；没登录或会话过期就返回 null。
import { headers } from "next/headers";
import { auth } from "@/lib/auth";
const session = await auth.api.getSession({
headers: await headers(),
});
// session 为 null：没登录
// session 不为 null：session.user.email 就是当前登录的邮箱headers() 是 Next.js 提供的函数，能在服务端组件和 Server Action 里拿到这次请求的请求头。从 Next.js 15 开始它是异步的，要写 await headers()。返回的 session 里有两部分：session.session 是会话记录本身（令牌、过期时间），session.user 是用户信息（id、邮箱、名字）。
这里有一个你昨天在浏览器里见过的东西：访问 /api/auth/get-session 返回的 JSON，结构和这里的 session 一样，只是一个是在浏览器里看，一个是在服务端代码里拿。
后台会有很多页面和很多 Server Action。如果每个地方都复制一遍“读会话、比邮箱、跳转”，总有一天会漏掉一处，或者改规则时忘改一处。所以把它写成一个函数，放在一个文件里，所有入口都调用它。这就是 Next.js 文档里说的“数据访问层”的思路：安全检查集中在一个地方，离数据越近越好。
dongge-web/lib/admin.ts
import "server-only";
import { cache } from "react";
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";
// 读取当前会话，并确认是不是东哥本人；不是就返回 null
export const getAdminSession = cache(async () => {
const session = await auth.api.getSession({
headers: await headers(),
});
if (!session) return null;
const adminEmail = process.env.ADMIN_EMAIL?.trim().toLowerCase();
if (!adminEmail) return null;
if (session.user.email.toLowerCase() !== adminEmail) return null;
return session;
});
// 在后台页面和 Server Action 开头调用：不是管理员就跳去登录页
export async function requireAdmin() {
const session = await getAdminSession();
if (!session) {
redirect("/login");
}
return session;
}逐行解释：
import "server-only"：给这个文件贴一张“只能在服务端用”的标签。如果哪天你不小心在客户端组件里导入了它，构建会直接报错，而不是悄悄把服务端代码打包进浏览器。这个包需要安装一次。cache(...)：React 提供的函数。同一次页面渲染里，如果页面、组件多处都调用了 getAdminSession()，只会真正查一次数据库，后面直接复用结果。session 是否存在，这是认证：有没有登录。trim() 去掉 .env 里不小心多打的空格，toLowerCase() 统一成小写，避免大小写不同导致比对失败。ADMIN_EMAIL 没配置，直接返回 null。宁可谁都进不去，也不要在配置缺失时放所有人进去。这叫“默认拒绝”。requireAdmin() 在不合格时调用 redirect("/login")。redirect 会抛出一个特殊的信号，让 Next.js 中断当前渲染或当前 Server Action，直接返回跳转响应，后面的代码一行都不会执行。有了 requireAdmin()，后台的每个 page.tsx 第一行就调用它：
export default async function AdminHomePage() {
const session = await requireAdmin();
// 走到这里，说明一定是管理员
const lookCount = await prisma.look.count();
// ...
}你也许会想：后台所有页面都套在 app/admin/layout.tsx 里面，只在 layout 里检查一次不是更省事吗？Next.js 官方文档专门提醒过不要这么做，原因有两个：
所以规则是：layout 只负责长相（导航栏、退出按钮），每个 page 自己查卡。这样哪怕以后有人新加一个后台页面，只要照着其他页面写，就不会漏掉检查。
为了以后不漏，你可以给自己定一个固定动作：每次新建后台文件，先问自己三个问题。第一，这是一个 page.tsx 吗？是的话第一行调用 requireAdmin()。第二，这是一个 "use server" 文件里导出的函数吗？是的话它的第一行也调用 requireAdmin()。第三，这个函数收到的参数是不是来自浏览器？是的话先校验再使用。这三条写在便签上贴在显示器边，比任何工具都管用。
为什么不合格时是“跳转到登录页”，而不是显示一个错误？对后台页面来说，没登录的人最需要的就是登录入口，直接送过去最顺手。对 Server Action 来说，跳转同样会中断后面的代码，数据库一行都不会动，安全效果是一样的。
这是今天最容易忽略的一点。DAY 43 你学过，Server Action 是写在服务端、由表单直接调用的函数。它用起来像普通函数调用，但本质上是一个 HTTP 接口：浏览器点按钮时，会往当前页面地址发一个 POST 请求，请求头里带着这个 Action 的编号。这个编号就写在发给浏览器的 JavaScript 里，懂一点技术的人都能找到，然后用脚本直接发请求，完全不经过你的页面。
你可以亲眼看到这个请求：在后台页面打开开发者工具的 Network 面板，点一次按钮，列表里会多出一条发往当前页面地址的 POST 请求。点开它，请求头里有一项 Next-Action，值是一长串字母和数字，这就是 Action 的编号；请求体里是这次调用要传的数据。只要把这条请求原样复制下来，在终端里用 curl 就能重新发送，还能随意改动里面的内容再发。浏览器能做到的事，脚本都能做到，这就是为什么我们说它是“公开的入口”。
也就是说，“页面有检查”不代表“Action 有检查”。有人可以绕过页面，直接调用你的“删除 look”。Next.js 文档的原话意思是：要像对待公开 API 一样对待 Server Action，每一个都要自己验证身份。
今天先写一个最小的后台操作：在后台首页给 look 切换“上架 / 下架”。
dongge-web/app/admin/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
export async function togglePublished(lookId: number) {
await requireAdmin();
if (!Number.isInteger(lookId) || lookId <= 0) {
throw new Error("look id 不对");
}
const look = await prisma.look.findUnique({ where: { id: lookId } });
if (!look) {
throw new Error("找不到这条 look");
}
await prisma.look.update({
where: { id: lookId },
data: { published: !look.published },
});
revalidatePath("/", "layout");
}第一行业务代码就是 await requireAdmin()，不是管理员直接跳走，下面的数据库操作不会发生。接着检查 lookId 是不是正整数：这个参数虽然是你在页面上绑定的，但它是从浏览器传回来的，别人可以改成任何值，所以要验证。然后查出这条 look，把 published 取反保存。最后 revalidatePath("/", "layout") 让全站的页面缓存失效，前台下次打开就是最新状态。
Int @id @default(autoincrement())。如果你用的是字符串 id，就把类型改成 string，检查改成“不是空字符串”。你在网上搜“Next.js 保护页面”，会看到很多教程用 middleware.ts：在项目根目录放一个文件，每个请求到达页面之前先经过它，没登录就重定向。Next.js 16 把这个文件改名为 proxy.ts，导出的函数也从 middleware 改成 proxy，旧名字已经标记为废弃。官方给了自动迁移命令 npx @next/codemod@canary middleware-to-proxy .。改名的原因之一，就是官方不希望大家把它当成万能的“中间件”，它更像站在应用前面的一道网络关卡。
dongge-web/proxy.ts
import { NextResponse, type NextRequest } from "next/server";
import { getSessionCookie } from "better-auth/cookies";
export function proxy(request: NextRequest) {
const sessionCookie = getSessionCookie(request);
if (!sessionCookie) {
return NextResponse.redirect(new URL("/login", request.url));
}
return NextResponse.next();
}
export const config = {
matcher: ["/admin/:path*"],
};matcher 规定只有 /admin 和它下面的地址才经过这个函数，:path* 表示“后面有零段或多段路径”。getSessionCookie 是 Better Auth 提供的工具，只检查请求里有没有会话 Cookie。没有就跳去登录页，有就放行。
注意它只看“有没有”，不看“真不真、过没过期、是不是管理员”。随便伪造一个同名 Cookie 就能骗过它。Better Auth 文档在这段代码旁边写得很直白：这样做不安全，只适合用来“乐观地”提前跳转，真正的检查要放在每个页面和接口里。Next.js 文档也提醒：proxy 的 matcher 一旦改错，或者某个 Server Action 被挪到另一个路由下，保护就会悄悄失效。
那为什么还要写它？因为它便宜又快：明显没登录的人，在页面开始渲染前就被送去登录页，不用白白跑一遍页面代码。它是锦上添花，页面和 Server Action 里的 requireAdmin() 才是真正的门禁。今天下午你会亲手关掉 proxy，证明没有它，后台依然安全。
退出登录要做两件事：服务端删掉 session 表里那一行，浏览器清掉 Cookie。Better Auth 的 authClient.signOut() 一次做完。它要在浏览器里被点击触发，所以写成客户端组件：
dongge-web/app/admin/logout-button.tsx
"use client";
import { useRouter } from "next/navigation";
import { authClient } from "@/lib/auth-client";
export function LogoutButton() {
const router = useRouter();
async function handleLogout() {
await authClient.signOut();
router.push("/login");
router.refresh();
}
return (
<button type="button" onClick={handleLogout}
className="rounded border px-3 py-1 text-sm hover:bg-neutral-100">
退出登录
</button>
);
}退出后跳回登录页，router.refresh() 清掉页面上还留着的旧数据。因为 session 表里那一行已经删了，就算有人事先复制了你的 Cookie，这个 Cookie 也作废了。所以在网吧、朋友电脑上用完后台，一定要点退出，而不是直接关窗口。
明天你会在这个后台里做 look 的完整增删改查，每个新页面、每个新 Action 都要沿用今天的规则。
安装 server-only，确认 ADMIN_EMAIL
cd ~/code/dongge-web
npm install server-only
grep ADMIN_EMAIL .envgrep 打印出昨天写进 .env 的那一行 ADMIN_EMAIL=...，邮箱和你创建管理员时用的一样。自己写 lib/admin.ts
这是今天的核心安全代码，请自己敲，不要让 Claude 写。照第 3 节的代码写，敲到每一个 return null 时，想一想它挡住的是哪种人。写完可以让 Claude 审查，但只让它指出问题，不让它改。
让 Claude 写后台布局样板
布局只是导航栏，属于样板代码，可以交给 Claude。它写完后你检查：布局里没有做登录检查，并且有一行注释说明原因。参考结果：
dongge-web/app/admin/layout.tsx
import Link from "next/link";
import { LogoutButton } from "./logout-button";
// 注意：这里不做登录检查。布局在页面切换时不会重新执行，
// 真正的检查写在每个 page 和每个 Server Action 里。
export default function AdminLayout({ children }: { children: React.ReactNode }) {
return (
<div className="min-h-screen bg-neutral-50">
<header className="border-b bg-white">
<nav className="mx-auto flex max-w-5xl items-center gap-4 px-4 py-3 text-sm">
<Link href="/admin" className="font-bold">东哥后台</Link>
<Link href="/admin/looks">Looks</Link>
<Link href="/admin/questions">提问箱</Link>
<div className="ml-auto">
<LogoutButton />
</div>
</nav>
</header>
<main className="mx-auto max-w-5xl px-4 py-8">{children}</main>
</div>
);
}再新建 app/admin/logout-button.tsx，内容照第 7 节。导航里的 Looks 和提问箱页面明天和 DAY 50 才做，现在点进去是 404，属于正常。
写上架 / 下架的 Server Action
新建 app/admin/actions.ts，照第 5 节写。requireAdmin() 和 id 检查这两段你自己敲。
写后台首页
dongge-web/app/admin/page.tsx
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { togglePublished } from "./actions";
export default async function AdminHomePage() {
const session = await requireAdmin();
const [lookCount, pendingCount, recentLooks] = await Promise.all([
prisma.look.count(),
prisma.question.count({ where: { status: "PENDING" } }),
prisma.look.findMany({
orderBy: { createdAt: "desc" },
take: 5,
include: { world: true },
}),
]);
return (
<div className="space-y-8">
<div>
<h1 className="text-2xl font-bold">后台总览</h1>
<p className="mt-1 text-sm text-neutral-500">当前登录：{session.user.email}</p>
</div>
<div className="grid gap-4 sm:grid-cols-2">
<div className="rounded-lg border bg-white p-4">
<p className="text-sm text-neutral-500">Look 总数</p>
<p className="mt-1 text-3xl font-bold">{lookCount}</p>
</div>
<div className="rounded-lg border bg-white p-4">
<p className="text-sm text-neutral-500">待审核提问</p>
<p className="mt-1 text-3xl font-bold">{pendingCount}</p>
</div>
</div>
<section>
<h2 className="text-lg font-semibold">最近的 look</h2>
<ul className="mt-3 divide-y rounded-lg border bg-white">
{recentLooks.map((look) => (
<li key={look.id} className="flex items-center justify-between px-4 py-3">
<span>
{look.title}
<span className="ml-2 text-sm text-neutral-500">{look.world.name}</span>
</span>
<form action={togglePublished.bind(null, look.id)}>
<button type="submit" className="rounded border px-3 py-1 text-sm">
{look.published ? "下架" : "上架"}
</button>
</form>
</li>
))}
</ul>
</section>
</div>
);
}Promise.all 让三个查询同时发出，比一个一个等更快。togglePublished.bind(null, look.id) 把这条 look 的 id 预先“绑”进 Action，点按钮时就知道操作哪一条。
改登录页：已登录直接进后台，登录成功跳后台
把 app/login/page.tsx 改成异步组件，开头加两行：
import { redirect } from "next/navigation";
import { getAdminSession } from "@/lib/admin";
import { LoginForm } from "./login-form";
export const metadata = { title: "管理员登录" };
export default async function LoginPage() {
const session = await getAdminSession();
if (session) redirect("/admin");
return (
<main className="mx-auto max-w-sm px-4 py-16">
<h1 className="text-2xl font-bold">管理员登录</h1>
<p className="mt-2 text-sm text-neutral-500">这里只给东哥自己用。</p>
<LoginForm />
</main>
);
}再把 login-form.tsx 里登录成功后的 router.push("/") 改成 router.push("/admin")。
加上 proxy.ts
在项目根目录（和 app 文件夹同一层）新建 proxy.ts，内容照第 6 节。如果你以前照着旧教程建过 middleware.ts，运行官方命令迁移：npx @next/codemod@canary middleware-to-proxy .。然后重启 npm run dev。
验证一：未登录访问后台
打开一个无痕窗口（Cmd + Shift + N），直接输入 http://localhost:3000/admin。
/login。在正常窗口登录后，能看到“后台总览”、你的邮箱、两个数字和最近的 look。验证二：关掉 proxy，后台依然进不去
把 proxy.ts 临时改名为 proxy.ts.off，重启 npm run dev，再在无痕窗口访问 /admin。
/login。这次拦住你的是 page.tsx 里的 requireAdmin()，证明页面级检查才是真正的保护。验证三：登出后再点后台按钮
保持 proxy 关闭。在正常窗口开两个标签页，都打开 /admin。在标签页 B 点“退出登录”。回到标签页 A（页面还显示着后台），点某条 look 的“下架”。
做完把 proxy.ts.off 改回 proxy.ts，重启。
验证四：登录了但不是管理员
把 .env 里的 ADMIN_EMAIL 临时改成另一个邮箱，重启后访问 /admin。你明明登录着，却会被送回登录页：认证通过，授权失败。验证完改回来，再重启。
请 Claude 审查，然后提交
让 Claude 读今天的改动，按下方第 2 条提示词检查有没有漏掉检查的入口。确认无误后提交：
git add -A
git commit -m "保护后台：页面和 Server Action 都检查管理员，加退出登录和 proxy"/login 也拦了，或者登录页的判断写反了。matcher 只写 /admin/:path*，登录页只在 getAdminSession() 有结果时才跳后台。npm run dev 启动时读取，改完必须重启开发服务器。requireAdmin() 放进 try/catch 后，没登录也不跳转：redirect 是靠抛出一个特殊错误来工作的，被你的 catch 接住就失效了。requireAdmin() 写在 try 外面。proxy.ts，函数名改成 proxy。用官方 codemod 迁移，或手动改名。有人直接在浏览器输入 /admin 会怎样？有人绕过页面直接调用你的 Server Action 呢？
直接输入 /admin：proxy 先看有没有会话 Cookie，没有就跳 /login；就算 proxy 被绕过或配置错了，app/admin/page.tsx 第一行的 requireAdmin() 会在服务端查真实会话并比对管理员邮箱，不合格就 redirect("/login")，页面里的数据库查询不会执行。绕过页面直接调用 Server Action：Server Action 本质是一个能被任何人发 POST 请求调用的接口，所以每个 Action 开头都有 await requireAdmin()，没登录或不是管理员就中断，后面的修改不会发生；参数也要重新校验，因为它来自浏览器。
proxy.ts 里用 getSessionCookie 只检查 Cookie 是否存在，为什么不够？既然不够，为什么还要写它？
它不验证 Cookie 是真是假、有没有过期、是不是管理员，伪造一个同名 Cookie 就能通过；而且 matcher 改错或 Action 挪了位置，它就管不到了。写它是为了体验和效率：明显没登录的人在页面渲染前就被送去登录页。真正的保护是每个页面和每个 Server Action 里的 requireAdmin()。
为什么不在 app/admin/layout.tsx 里检查一次就完事？
layout 在后台页面之间切换时不会重新执行，检查不会每次都跑；layout 也不能阻止子页面渲染，页面里的查询照样会执行，数据可能被带到浏览器。所以检查要放在每个 page 和每个 Server Action 里，离数据最近的地方。
LookForm 组件完成新建和编辑，并用 Zod 在服务端校验，把错误显示在对应输入框下面。createLook、updateLook、deleteLook 三个 Server Action，每个开头都检查管理员身份、校验参数。昨天的后台首页只能给 look 上架、下架。今天要把 look 管理做完整：新建一条、改一条、删一条、看全部。这四个动作合起来叫 CRUD：Create（新建）、Read（读取）、Update（修改）、Delete（删除）。几乎所有后台系统，不管是电商还是博客，核心都是对几张表做 CRUD。
把它想成管理你的衣橱：“看全部”是打开衣柜扫一眼，“新建”是挂进一套新搭配，“修改”是给某套换条裤子，“删除”是把某套清出去。每一种动作对应一个页面或一个按钮：
| 动作 | 网址或位置 | 文件 |
|---|---|---|
| 看全部 | /admin/looks | app/admin/looks/page.tsx |
| 新建 | /admin/looks/new | app/admin/looks/new/page.tsx |
| 修改 | /admin/looks/3/edit | app/admin/looks/[id]/edit/page.tsx |
| 删除 | 列表每一行的“删除”按钮 | app/admin/looks/delete-button.tsx |
真正改数据库的代码集中在 app/admin/looks/actions.ts 里的三个 Server Action。页面只负责展示和收集输入，Action 负责检查和保存。这样安全检查只需要盯住一个文件。
今天的分工：表格、表单这类“长得差不多”的样板代码交给 Claude 写；校验规则、权限检查、参数检查这些业务逻辑你自己写，并且逐行读 Claude 的每一处改动。
Int @id @default(autoincrement())（自增整数），Look 有 title、description、imageUrl、published、createdAt、worldId 和关联字段 world。所以今天的代码里 id 都按正整数处理。prisma 用的是 lib/prisma.ts 的默认导出：import prisma from "@/lib/prisma"。列表页不需要交互，只是把数据摆出来，所以留在服务端组件里。它做三件事：检查管理员、查出所有 look（连同所属世界）、渲染成表格。
为什么用表格而不是卡片？前台给粉丝看，卡片好看；后台给你自己用，要的是一眼扫清楚、方便比较，表格最合适。HTML 表格由 table、thead（表头）、tbody（表体）、tr（一行）、th（表头格）、td（普通格）组成。
查询时用 include: { world: true }，Prisma 会顺着 worldId 把对应的世界一起查出来，你就能写 look.world.name 显示“街头”。这就是 DAY 41 学的 JOIN，Prisma 替你写了 SQL。
顺便区分一下 include 和 select：include 是“这张表的所有列，再加上关联的表”；select 是“我只要这几列”。列表页在服务端渲染，最后发给浏览器的只是生成好的表格，多查几列问题不大。但凡是要把数据交给客户端组件（带 "use client" 的组件）的地方，就用 select 只挑需要的列，因为交给客户端组件的数据会原样出现在浏览器里，任何人打开开发者工具都能看到。今天的新建页只把世界的 id 和名字交给表单，就是这个道理。
创建时间要显示成人看得懂的样子。DAY 15 你写过 formatDate，把日期变成“10月1日 周四”。今天把它搬进项目，并且加一个时区参数。为什么要时区？网站部署在 Vercel 上，服务器用的是 UTC 时间（伦敦冬令时的时间）。如果直接用 getDate()，晚上 11 点发的 look 可能显示成前一天或后一天。
dongge-web/lib/format.ts
const WEEKDAYS = ["周日", "周一", "周二", "周三", "周四", "周五", "周六"];
/**
* 把时间变成“10月1日 周四”。
* utcOffsetHours：你所在地区比 UTC 快几个小时。
* 默认 8（北京、新加坡、吉隆坡），泰国是 7。
*/
export function formatDate(date: Date, utcOffsetHours = 8): string {
const local = new Date(date.getTime() + utcOffsetHours * 60 * 60 * 1000);
const month = local.getUTCMonth() + 1;
const day = local.getUTCDate();
const weekday = WEEKDAYS[local.getUTCDay()];
return `${month}月${day}日 ${weekday}`;
}思路是：先把时间往后挪几个小时，变成你当地的时间，再用 getUTC... 系列方法读出月、日、星期。getUTCDay() 返回 0 到 6，0 是周日，正好对应数组下标。getUTCMonth() 从 0 开始数，所以要加 1。这个函数不读数据库、不依赖服务器所在地，同样的输入永远得到同样的输出，DAY 51 你会给它写测试。
DAY 44 你学过：前端校验只是方便用户，服务端校验才是底线，因为请求可以绕过页面直接发。look 的规则也用 Zod 写，放进 lib/validation.ts，和提问箱的规则放在一起。
dongge-web/lib/validation.ts（新增部分）
import * as z from "zod";
export const lookSchema = z.object({
title: z
.string({ error: "标题不能为空" })
.trim()
.min(1, "标题不能为空")
.max(40, "标题最多 40 个字"),
description: z.string().trim().max(500, "描述最多 500 个字"),
worldId: z.coerce
.number({ error: "请选择一个世界" })
.int()
.positive("请选择一个世界"),
published: z.boolean(),
});
export type LookFormValues = {
title: string;
description: string;
worldId: string;
published: boolean;
};
export type LookFormState = {
errors?: Partial<Record<keyof LookFormValues | "image", string[]>>;
message?: string;
values?: LookFormValues;
};逐行看规则：
trim() 先去掉两边空格，再用 min(1) 判断是否为空。这样只打了几个空格的标题也会被拦下。max(40) 限制长度。标题要放进卡片，太长会撑破排版，也防止有人塞进一大段文字。worldId 来自下拉框，表单里所有值都是字符串，比如 "2"。z.coerce.number() 先把它转成数字再检查。如果没选，值是空字符串，转出来是 0，positive() 就会报“请选择一个世界”。published 来自复选框。浏览器的规矩是：勾选时提交 "on"，不勾选时这个字段根本不出现。所以我们在 Action 里先把它转成 true 或 false，再交给 Zod。下面两个类型是给表单用的：LookFormValues 是用户刚刚填的原始值，LookFormState 是 Action 返回给表单的结果，里面可能有每个字段的错误、一句总体提示，以及用户刚填的值。为什么要把填过的值带回去？React 19 在表单提交完成后会自动重置表单，如果校验失败又不把值带回去，用户辛苦写的描述就没了。
如果你 DAY 44 的 questionSchema 放在别的文件，也没关系，今天新建 lib/validation.ts 放 lookSchema 就行。
所有改数据的操作都写在一个 "use server" 文件里。先看新建：
dongge-web/app/admin/looks/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import * as z from "zod";
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { lookSchema, type LookFormState, type LookFormValues } from "@/lib/validation";
// 把表单里的原始值读出来，统一变成字符串和布尔值
function readValues(formData: FormData): LookFormValues {
return {
title: String(formData.get("title") ?? ""),
description: String(formData.get("description") ?? ""),
worldId: String(formData.get("worldId") ?? ""),
published: formData.get("published") === "on",
};
}
function isValidId(id: number) {
return Number.isInteger(id) && id > 0;
}
export async function createLook(
_prev: LookFormState,
formData: FormData,
): Promise<LookFormState> {
await requireAdmin();
const values = readValues(formData);
const parsed = lookSchema.safeParse(values);
if (!parsed.success) {
return { errors: z.flattenError(parsed.error).fieldErrors, values };
}
await prisma.look.create({ data: parsed.data });
revalidatePath("/", "layout");
redirect("/admin/looks");
}
export async function updateLook(
id: number,
_prev: LookFormState,
formData: FormData,
): Promise<LookFormState> {
await requireAdmin();
if (!isValidId(id)) {
return { message: "look id 不对" };
}
const values = readValues(formData);
const parsed = lookSchema.safeParse(values);
if (!parsed.success) {
return { errors: z.flattenError(parsed.error).fieldErrors, values };
}
await prisma.look.update({ where: { id }, data: parsed.data });
revalidatePath("/", "layout");
redirect("/admin/looks");
}
export async function deleteLook(id: number) {
await requireAdmin();
if (!isValidId(id)) {
throw new Error("look id 不对");
}
await prisma.look.delete({ where: { id } });
revalidatePath("/", "layout");
}按顺序解释：
readValues 和 isValidId 没有 export，只在这个文件内部用。"use server" 文件里导出的每个函数都会变成可以从外面调用的接口，所以辅助函数不要导出。await requireAdmin()，这是昨天定下的规矩。createLook 的参数是 (上一次的状态, 表单数据)，这是配合 React 的 useActionState 使用时的固定格式。第一个参数我们用不到，名字前面加下划线表示“故意不用”。safeParse 不会抛错，而是返回一个结果：成功时 parsed.data 是清洗过的数据（标题去掉了空格、worldId 变成了数字）；失败时用 z.flattenError(...).fieldErrors 把错误整理成 { title: ["标题不能为空"] } 这样按字段分组的形式，连同用户填的值一起返回给表单。parsed.data，而不是 values。只有通过校验的数据才进数据库。revalidatePath("/", "layout") 让全站页面缓存失效，前台下次访问就会重新查数据库。redirect("/admin/looks") 保存成功后回到列表。注意它必须在最后、不能放在 try/catch 里，原因昨天讲过。updateLook 比 createLook 多一个 id 参数。编辑页会用 updateLook.bind(null, look.id) 把 id 预先绑进去，绑完之后它的样子就和 createLook 一样了，所以两者可以共用一个表单组件。还有一种情况值得想一想：你在两个标签页里打开了同一条 look，在一个标签页里删掉它，又在另一个标签页里点保存。这时 prisma.look.update 找不到这条记录，会抛出错误，页面显示出错提示。这不会弄坏数据，对只有你一个人用的后台来说可以接受。以后如果想更友好，可以先用 findUnique 查一下，查不到就返回一句“这条 look 已经不存在了”。
新建和编辑的表单长得一模一样，区别只有两点：编辑时输入框里要预先填好旧内容；提交时调用的 Action 不同。所以做一个组件，用 props 区分：
dongge-web/app/admin/looks/look-form.tsx
"use client";
import { useActionState } from "react";
import Link from "next/link";
import type { LookFormState } from "@/lib/validation";
type World = { id: number; name: string };
type LookDefaults = {
title: string;
description: string;
worldId: number;
published: boolean;
};
type Props = {
action: (state: LookFormState, formData: FormData) => Promise<LookFormState>;
worlds: World[];
look?: LookDefaults;
};
export function LookForm({ action, worlds, look }: Props) {
const [state, formAction, pending] = useActionState(action, {});
const v = state.values;
return (
<form action={formAction} className="max-w-xl space-y-5">
<div>
<label htmlFor="title" className="block text-sm font-medium">标题</label>
<input id="title" name="title" defaultValue={v?.title ?? look?.title ?? ""}
className="mt-1 w-full rounded border px-3 py-2" />
{state.errors?.title && (
<p className="mt-1 text-sm text-red-600">{state.errors.title[0]}</p>
)}
</div>
<div>
<label htmlFor="description" className="block text-sm font-medium">描述</label>
<textarea id="description" name="description" rows={4}
defaultValue={v?.description ?? look?.description ?? ""}
className="mt-1 w-full rounded border px-3 py-2" />
{state.errors?.description && (
<p className="mt-1 text-sm text-red-600">{state.errors.description[0]}</p>
)}
</div>
<div>
<label htmlFor="worldId" className="block text-sm font-medium">世界</label>
<select id="worldId" name="worldId"
defaultValue={v?.worldId ?? String(look?.worldId ?? "")}
className="mt-1 w-full rounded border px-3 py-2">
<option value="">请选择</option>
{worlds.map((world) => (
<option key={world.id} value={world.id}>{world.name}</option>
))}
</select>
{state.errors?.worldId && (
<p className="mt-1 text-sm text-red-600">{state.errors.worldId[0]}</p>
)}
</div>
<div className="flex items-center gap-2">
<input id="published" name="published" type="checkbox"
defaultChecked={v?.published ?? look?.published ?? false} />
<label htmlFor="published" className="text-sm">发布到前台</label>
</div>
{state.message && <p className="text-sm text-red-600">{state.message}</p>}
<div className="flex items-center gap-3">
<button type="submit" disabled={pending}
className="rounded bg-black px-4 py-2 text-white disabled:opacity-50">
{pending ? "保存中…" : "保存"}
</button>
<Link href="/admin/looks" className="text-sm underline">取消</Link>
</div>
</form>
);
}关键点：useActionState(action, {}) 返回三样东西：state 是 Action 最近一次返回的结果，formAction 是包装后交给 form 的函数，pending 表示是否正在提交，用来禁用按钮、防止连点（DAY 44 学过）。每个输入框的默认值按顺序取：先取“刚才提交失败时带回来的值”，没有就取“编辑时的旧内容”，再没有就是空。这个组件本身没有任何权限判断，因为它运行在浏览器里，判断写在这里也没用。
你可能记得 DAY 30 学过“受控组件”：用 useState 保存输入框的值，每次输入都更新 state。这里没用它，而是用 defaultValue 只给一个初始值，之后输入框自己管理内容，提交时由浏览器把所有带 name 的字段打包成 FormData。这种写法叫“非受控”，代码更少，而且和 Server Action 配合得最自然。只有在需要边输入边做事（比如实时显示还能输入多少字）时，才需要换成受控写法。
为什么表单一定是客户端组件？因为 useActionState 是一个 Hook，Hook 只能在客户端组件里用；而且“提交中禁用按钮”“显示错误”都是交互。页面文件本身仍然是服务端组件，负责查世界列表、查旧内容，再把结果通过 props 交给表单。
删除不能撤销，误点一下，你拍了一下午的斯诺克造型就没了。所以点“删除”时先弹一个确认框：
dongge-web/app/admin/looks/delete-button.tsx
"use client";
import type { FormEvent } from "react";
type Props = {
action: () => Promise<void>;
title: string;
};
export function DeleteLookButton({ action, title }: Props) {
function handleSubmit(event: FormEvent<HTMLFormElement>) {
if (!window.confirm(`确定删除「${title}」吗？删除后不能恢复。`)) {
event.preventDefault();
}
}
return (
<form action={action} onSubmit={handleSubmit}>
<button type="submit" className="text-red-600 underline">删除</button>
</form>
);
}window.confirm 弹出浏览器自带的确认框，点“取消”返回 false，我们就调用 preventDefault() 阻止提交，Action 不会被调用。
但要记住，确认框只防“手滑”，不防“坏人”。它运行在浏览器里，攻击者根本不会经过这个框，而是直接调用 deleteLook。所以真正的保护还是 deleteLook 第一行的 requireAdmin()。客户端负责体验，服务端负责安全，两者分工不能混。
有了“发布”开关，你就可以先建一条草稿，照片和文案都满意了再勾选发布。拍完一组街头造型，可以当天先把能想到的文字记进去，第二天挑好照片、改好描述再上架，粉丝看到的永远是完成品。前提是前台查询要加上条件，只取 published 为 true 的：
const looks = await prisma.look.findMany({
where: { published: true },
orderBy: { createdAt: "desc" },
include: { world: true },
});DAY 42 你已经在首页 app/page.tsx 和世界详情页 app/world/[slug]/page.tsx 的查询里写了 published: true，当时它还没什么用，因为没有地方能改这个值；今天有了发布开关，它才真正起作用。以后新增任何读 look 的前台页面，都要记得带上这个条件，漏掉一处，草稿就会被粉丝看到。后台列表则不加这个条件，因为你要看到全部。
写文案时也守住“说事情不说情话”：标题写清楚是什么，比如“斯诺克之夜：深灰马甲”；描述写具体搭配和场景，比如“深灰马甲配白衬衫、黑色牛津鞋，袖口卷两折，方便架杆”。不写空泛的形容词。
明天你会给 look 加上照片上传。
写 formatDate
新建 lib/format.ts。把你 DAY 15 写的 formatDate 找出来，对照第 2 节改造：加上 utcOffsetHours 参数，改用 getUTC... 方法。这是业务逻辑，自己写。如果你人在泰国，把默认值改成 7。
写 lookSchema
打开或新建 lib/validation.ts，照第 3 节加上 lookSchema 和两个类型。规则里的数字（40、500）你可以按自己的需要改，改了就记住，DAY 51 写测试要用。
写三个 Server Action
新建 app/admin/looks/actions.ts。可以让 Claude 先生成骨架，但下面这些你自己写：每个 Action 第一行的 requireAdmin()、isValidId 检查、用 parsed.data 保存、revalidatePath。写完对照第 4 节逐行检查。
让 Claude 写表单组件
用下方第 1 条提示词让 Claude 写 app/admin/looks/look-form.tsx。写完你对照第 5 节检查：每个输入框都有 label 并用 htmlFor 关联；label 文字是“标题”“描述”“世界”“发布到前台”，按钮文字是“保存”（DAY 52 的自动化测试会用这些文字找元素）；组件里没有任何权限判断。
新建页面
dongge-web/app/admin/looks/new/page.tsx
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { createLook } from "../actions";
import { LookForm } from "../look-form";
export default async function NewLookPage() {
await requireAdmin();
const worlds = await prisma.world.findMany({
orderBy: { id: "asc" },
select: { id: true, name: true },
});
return (
<div>
<h1 className="text-2xl font-bold">新建 look</h1>
<div className="mt-6">
<LookForm action={createLook} worlds={worlds} />
</div>
</div>
);
}select 只取 id 和 name，传给客户端组件的数据越少越好。
编辑页面
dongge-web/app/admin/looks/[id]/edit/page.tsx
import { notFound } from "next/navigation";
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { updateLook } from "../../actions";
import { LookForm } from "../../look-form";
export default async function EditLookPage({
params,
}: {
params: Promise<{ id: string }>;
}) {
await requireAdmin();
const { id } = await params;
const lookId = Number(id);
if (!Number.isInteger(lookId) || lookId <= 0) notFound();
const [look, worlds] = await Promise.all([
prisma.look.findUnique({ where: { id: lookId } }),
prisma.world.findMany({ orderBy: { id: "asc" }, select: { id: true, name: true } }),
]);
if (!look) notFound();
return (
<div>
<h1 className="text-2xl font-bold">编辑 look</h1>
<div className="mt-6">
<LookForm
action={updateLook.bind(null, look.id)}
worlds={worlds}
look={{
title: look.title,
description: look.description ?? "",
worldId: look.worldId,
published: look.published,
}}
/>
</div>
</div>
);
}在 Next.js 16 里，params 是一个 Promise，要先 await。网址里的 id 是字符串，比如 "abc" 这种乱写的值，Number 转出来是 NaN，直接显示 404。
删除按钮和列表页
新建 app/admin/looks/delete-button.tsx，内容照第 6 节。然后写列表页，表格部分可以让 Claude 写：
dongge-web/app/admin/looks/page.tsx
import Link from "next/link";
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { formatDate } from "@/lib/format";
import { deleteLook } from "./actions";
import { DeleteLookButton } from "./delete-button";
export default async function AdminLooksPage() {
await requireAdmin();
const looks = await prisma.look.findMany({
orderBy: { createdAt: "desc" },
include: { world: true },
});
return (
<div>
<div className="flex items-center justify-between">
<h1 className="text-2xl font-bold">Looks</h1>
<Link href="/admin/looks/new" className="rounded bg-black px-4 py-2 text-sm text-white">
新建 look
</Link>
</div>
{looks.length === 0 ? (
<p className="mt-8 text-neutral-500">还没有 look，先新建一条。</p>
) : (
<div className="mt-6 overflow-x-auto">
<table className="w-full border-collapse bg-white text-sm">
<thead>
<tr className="border-b text-left text-neutral-500">
<th className="px-3 py-2">标题</th>
<th className="px-3 py-2">世界</th>
<th className="px-3 py-2">状态</th>
<th className="px-3 py-2">创建时间</th>
<th className="px-3 py-2">操作</th>
</tr>
</thead>
<tbody>
{looks.map((look) => (
<tr key={look.id} className="border-b">
<td className="px-3 py-2">{look.title}</td>
<td className="px-3 py-2">{look.world.name}</td>
<td className="px-3 py-2">{look.published ? "已发布" : "草稿"}</td>
<td className="px-3 py-2">{formatDate(look.createdAt)}</td>
<td className="px-3 py-2">
<div className="flex gap-3">
<Link href={`/admin/looks/${look.id}/edit`} className="underline">编辑</Link>
<DeleteLookButton action={deleteLook.bind(null, look.id)} title={look.title} />
</div>
</td>
</tr>
))}
</tbody>
</table>
</div>
)}
</div>
);
}overflow-x-auto 让表格在手机上可以左右滑动，而不是把整个页面撑宽。
确认前台只显示已发布的 look
在 VS Code 里按 Cmd + Shift + F 全局搜索 published: true，确认首页和世界详情页的查询里都有它（DAY 42 写的）。如果你后来又加过别的读 look 的前台页面，也要带上这个条件。
app/admin 以外、所有读取 look 的查询都带有 published: true。完整走一遍
运行 npm run dev，登录后台，依次做：
安全自查
开两个标签页都打开 /admin/looks，在一个标签页退出登录，回到另一个点某条的“删除”并确认。应该被带到登录页，重新登录后那条 look 还在。然后用下方第 2 条提示词让 Claude 审查今天的改动。
提交
git add -A
git commit -m "后台 looks：列表、新建、编辑、删除"values，输入框的 defaultValue 优先用它。params 和 searchParams 都要先 await 再取值。revalidatePath("/", "layout")，以及前台页面是不是读的数据库而不是写死的数组。redirect 包在了 try/catch 里。把数据库操作放进 try，redirect 放在 try/catch 外面最后执行。handleSubmit 是否绑在了 form 的 onSubmit 上，而不是按钮的 onClick；以及取消时是否调用了 event.preventDefault()。删除操作为什么要在服务端再检查一次登录状态？
因为 deleteLook 是 Server Action，本质上是一个任何人都能发 POST 请求调用的接口。列表页有检查、确认框会弹出，都只是在“正常点按钮”的路径上；攻击者可以不打开页面、不经过确认框，直接带着 Action 编号发请求。只有 deleteLook 自己第一行调用 requireAdmin()，在服务端核对真实会话，才能保证不是你就删不了。确认框只防手滑，服务端检查才防坏人。
为什么新建和编辑共用一个 LookForm，而 Server Action 分成两个？
两者的界面完全一样，共用组件可以少写一半代码，改样式只改一处。但两者对数据库做的事不同：一个是 create，一个是 update，而且 update 需要知道改哪一条、要检查 id。所以 Action 分开，用 bind 把 id 绑进 updateLook，让它和 createLook 的参数格式一致，就能交给同一个表单。
updateLook 的 id 是你自己在编辑页里绑进去的，为什么在 Action 里还要检查它是不是正整数？
绑定的值最终会随请求从浏览器发回服务端，服务端无法确定它没被改过。原则是：服务端收到的所有输入都不可信，都要校验。检查能挡住 NaN、负数、小数这类异常值，避免数据库报错或误操作。
vercel env pull 把凭证拉到本地。next/image 显示照片。昨天你能在后台新建、编辑 look 了，但 look 只有文字。穿搭内容没有照片，说服力差一大截。今天给 look 加上照片。
第一个问题：照片存哪？你可能想直接存进 Neon 数据库。技术上可以，但几乎没人这么做。数据库擅长存一行一行的小数据，查得快、排序快；一张手机照片动辄几 MB，塞进去会让数据库变大变慢，备份也变重，而且每次展示图片都要经过你的服务器转一手。
打个比方：衣服放在衣柜里，账本上只记“那件深灰马甲在左边第二格”。图片放在专门存文件的地方，叫对象存储；数据库里只存一个网址，就是 Look 表里预留的 imageUrl 字段。前台显示时，浏览器拿着网址直接去对象存储取图，不经过你的服务器，也不占数据库。
那放进项目的 public 文件夹行不行？DAY 03 的旧官网就是把照片放在 looks/ 文件夹里一起部署的。那种做法适合“写代码时就确定”的图片，比如头像、Logo。后台上传是网站运行时才发生的事，而 Vercel 上的服务端函数运行在临时环境里，不能往项目文件夹里写文件，就算写进去，下次部署也会被清掉。想加一张照片就改代码、重新部署，也违背了做后台的初衷：以后更新内容不用再改代码。所以运行时上传的文件，要放进独立的存储服务。
我们用的对象存储是 Vercel Blob。“Blob”是“一大块二进制数据”的意思，存进去的每个文件都叫一个 blob。它和 Vercel 项目直接打通，不用另外注册账号。
普通表单提交时，浏览器把字段拼成 title=...&description=... 这样的文字发出去。带文件的表单不一样，浏览器会用一种叫 multipart/form-data 的格式，把请求体切成好几段：一段是标题，一段是描述，一段是照片的二进制内容。你用 React 的 form action 时，这些细节浏览器和 Next.js 都替你处理好了。
在 Server Action 里，照片和其他字段一样从 formData 取，只不过取出来的是一个 File 对象，它有三个常用属性：name（文件名，比如 IMG_2031.jpg）、size（字节数）、type（浏览器猜的类型，比如 image/jpeg）。
上传有大小限制，而且不止一层，你要心里有数：
next.config.ts 里把它调大一点。手机拍的原图常常超过 4MB。上传前在手机相册里用“编辑”或截图、导出成较小尺寸，就能压到 1 到 2MB。网站上显示的图片宽度不过几百像素，原图的清晰度本来就用不上。
创建 Blob 存储时要选访问方式，而且建好以后不能改：
look 照片本来就是给粉丝看的，选 Public。代价是：只要网址泄露，图片就能被看到。所以不要把不想公开的照片传进这个存储，哪怕是“先传上去，还没发布”的草稿。
公开存储里每个文件的网址长这样：https://一串编号.public.blob.vercel-storage.com/looks/look-随机字符.jpg。上传时加上 addRandomSuffix: true，Vercel 会在文件名后面加一段随机字符，两张同名照片不会互相覆盖，网址也猜不出来。
代码怎么证明“我有权限往这个存储里传文件”？把存储连接到 Vercel 项目后，Vercel 会自动给项目加上环境变量，其中包括 BLOB_READ_WRITE_TOKEN（长期有效的读写令牌），以及一组更新的、会自动轮换的凭证（BLOB_STORE_ID 和 VERCEL_OIDC_TOKEN）。@vercel/blob 这个包会自动读取它们，代码里一个密钥都不用写。本地开发时，用 Vercel 命令行把这些变量拉到 .env.local。
BLOB_READ_WRITE_TOKEN 能往你的存储里写任何文件、删任何文件。它和数据库地址一样，只能待在 .env 文件和 Vercel 的环境变量里，不提交 Git，不贴到聊天里。Vercel Blob 在 Hobby 计划里有免费额度，超出会按量计费，隔一段时间去 Vercel 的 Usage 页面看一眼。表单里的 accept="image/jpeg,image/png,image/webp" 能让文件选择框默认只显示图片，但它只是给正常用户的便利。有人可以在开发者工具里删掉这个属性，或者干脆不用你的页面，直接用脚本往 Server Action 发请求。浏览器里的任何限制，都能被绕过。
如果服务端不检查，会发生什么？
还有一个容易掉进去的坑：文件名和 file.type 都不可信。文件名谁都能改，把 virus.exe 改成 snooker.jpg 只需要一秒；file.type 是浏览器根据扩展名猜的，而且请求可以伪造。可靠的办法是看文件内容本身：每种图片格式的前几个字节是固定的，叫“文件签名”或“魔数”：
| 格式 | 开头的字节（十六进制） |
|---|---|
| JPG | FF D8 FF |
| PNG | 89 50 4E 47 0D 0A 1A 0A |
| WebP | 第 0 到 3 字节是 RIFF，第 8 到 11 字节是 WEBP |
这就像验货：不看箱子上贴的标签，而是打开箱子看里面是什么。
把检查写成独立的函数，放进 lib/image.ts。这是今天的安全核心，要你自己写。
dongge-web/lib/image.ts
export const MAX_IMAGE_BYTES = 4 * 1024 * 1024; // 4MB
export type ImageType = "image/jpeg" | "image/png" | "image/webp";
export const EXTENSIONS: Record<ImageType, string> = {
"image/jpeg": "jpg",
"image/png": "png",
"image/webp": "webp",
};
const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
// 根据文件开头的字节判断真实格式，认不出就返回 null
export function detectImageType(bytes: Uint8Array): ImageType | null {
if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
return "image/jpeg";
}
if (bytes.length >= 8 && PNG_SIGNATURE.every((b, i) => bytes[i] === b)) {
return "image/png";
}
if (
bytes.length >= 12 &&
String.fromCharCode(...bytes.slice(0, 4)) === "RIFF" &&
String.fromCharCode(...bytes.slice(8, 12)) === "WEBP"
) {
return "image/webp";
}
return null;
}
type CheckResult = { ok: true; type: ImageType } | { ok: false; error: string };
export async function checkImage(file: File): Promise<CheckResult> {
if (file.size > MAX_IMAGE_BYTES) {
return { ok: false, error: "图片不能超过 4MB" };
}
const head = new Uint8Array(await file.slice(0, 12).arrayBuffer());
const type = detectImageType(head);
if (!type) {
return { ok: false, error: "只支持 JPG、PNG、WebP 格式的图片" };
}
return { ok: true, type };
}逐段解释：
4 * 1024 * 1024：1KB 是 1024 字节，1MB 是 1024KB，所以 4MB 是这么多字节。写成乘法比写一个 4194304 更容易看懂。ImageType 是 DAY 26 学过的字面量联合类型，只允许三种值。EXTENSIONS 把类型对应到扩展名，上传时用来给文件起名。Uint8Array 是“一串 0 到 255 的数字”，正好用来表示字节。0xff 是十六进制写法，等于 255。bytes.length，防止文件太短时读到不存在的位置。every 逐个比较（DAY 16 学过的数组方法）。WebP 用 String.fromCharCode 把字节转成字母，再和 "RIFF"、"WEBP" 比较。checkImage 先查大小，再用 file.slice(0, 12) 只读前 12 个字节，不用把整个文件读进内存。ok 为 true 时一定有 type，为 false 时一定有 error。调用的地方判断一下 ok，TypeScript 就知道能用哪个属性。detectImageType 只接收字节、只返回结果，不碰网络和数据库，这种函数 DAY 51 最好测试。
@vercel/blob 提供两个今天要用的函数：put 上传，del 删除。在 Action 文件里加两个辅助函数：
import { put, del } from "@vercel/blob";
import { checkImage, EXTENSIONS } from "@/lib/image";
// 从表单取出图片；没选文件时浏览器也会发一个空文件，要排除
function readImage(formData: FormData): File | null {
const file = formData.get("image");
if (file instanceof File && file.size > 0) return file;
return null;
}
// 检查并上传，成功返回网址，失败返回错误信息
async function uploadImage(file: File): Promise<{ url: string } | { error: string }> {
const checked = await checkImage(file);
if (!checked.ok) return { error: checked.error };
const blob = await put(`looks/look.${EXTENSIONS[checked.type]}`, file, {
access: "public",
addRandomSuffix: true,
contentType: checked.type,
});
return { url: blob.url };
}
// 删旧图片；删失败只记日志，不影响页面
async function removeImage(url: string) {
try {
await del(url);
} catch (error) {
console.error("删除旧图片失败", url, error);
}
}注意三处细节。第一，文件名用我们自己定的 looks/look.jpg，不用用户上传时的文件名，因为用户的文件名可能很长、带奇怪字符。looks/ 前缀会在存储里形成一个文件夹，方便整理。第二，contentType 用我们检查出的真实类型，而不是浏览器报的。第三，access: "public" 要和存储的访问方式一致。
顺序也有讲究。编辑时换照片：先上传新图，再更新数据库，最后删旧图。如果中间某一步失败，最坏的情况是 Blob 里多了一张没人用的旧图，占一点空间，但网站显示始终正常。反过来先删旧图，万一数据库更新失败，前台就会指向一张已经不存在的图。删除 look 时也一样：先删数据库记录，再删图片。
还有一点：先校验文字字段，再处理图片。标题没填的话直接返回错误，就不会白白上传一张图。
Next.js 的 Image 组件会自动把大图压缩成适合屏幕的尺寸、转成更省流量的格式、滚动到附近才加载。但出于安全考虑，它只处理你允许的外部域名，要在 next.config.ts 里用 remotePatterns 声明：
dongge-web/next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
experimental: {
serverActions: {
bodySizeLimit: "5mb",
},
},
images: {
remotePatterns: [
{
protocol: "https",
hostname: "*.public.blob.vercel-storage.com",
pathname: "/**",
},
],
},
};
export default nextConfig;bodySizeLimit: "5mb" 把 Server Action 的请求体上限从 1MB 调到 5MB，比我们自己的 4MB 规则略大，给表单其他字段和格式开销留空间。hostname 里的 * 匹配一段子域名，也就是你存储的那串编号。如果你的 next.config.ts 里已经有别的配置，把这两块合并进去，不要整个覆盖。
前台卡片里这样用：
{look.imageUrl ? (
<Image
src={look.imageUrl}
alt={look.title}
width={600}
height={800}
sizes="(min-width: 768px) 33vw, 100vw"
className="aspect-[3/4] w-full object-cover"
/>
) : (
<div className="flex aspect-[3/4] items-center justify-center bg-neutral-100 text-sm text-neutral-400">
暂无照片
</div>
)}width 和 height 告诉 Next.js 图片的比例（3:4 竖图），让页面提前留好位置，加载时不跳动。sizes 说明图片在不同屏幕上大概占多宽：电脑上三列各占三分之一，手机上占满，Next.js 据此挑合适的尺寸。object-cover 让图片填满方框、多余部分裁掉。alt 用 look 的标题，读屏软件会读出来。没有照片的旧 look 显示一个灰色占位块。
明天回到提问箱，给粉丝的提问加上审核流程。
装 Vercel 命令行并关联项目
npm install -g vercel
vercel login
cd ~/code/dongge-web
vercel linkvercel login 会打开浏览器让你确认登录。dongge-web 还没有部署过（DAY 54 才上线），所以 vercel link 问是否关联已有项目时选否，按提示新建一个名为 dongge-web 的项目，其余选项用默认值。如果它问要不要连接 Git 仓库，也先选否：现在连上的话，每次推送都会触发一次缺少环境变量、注定失败的部署，DAY 54 配好一切再连。关联信息保存在项目里的 .vercel 文件夹，它默认已被忽略，不会提交。
建一个公开的 Blob 存储
打开 Vercel 网站，进入 dongge-web 项目，左侧点 Storage，点 Create，选 Blob，点 Continue。访问方式选 Public，名字填 dongge-images，区域选离你近的（例如新加坡），环境三个都勾上：Production、Preview、Development。点创建。
把凭证拉到本地
vercel env pull它会把 Development 环境的变量写进 .env.local。只看变量名，不要把值打印出来：
grep -o '^[A-Z_]*' .env.local
git check-ignore -v .env.localBLOB_READ_WRITE_TOKEN；第二条命令输出了一行 .gitignore 规则，说明这个文件不会被提交。安装 SDK，改 next.config.ts
npm install @vercel/blob然后照第 7 节修改 next.config.ts，改完重启 npm run dev。
自己写 lib/image.ts
照第 5 节写。写 detectImageType 时，先对照表格把三种格式的字节抄在纸上，再写代码。写完在 VS Code 里找一张 JPG 照片，用下面的命令看看它开头的字节，对照一下：
xxd -l 12 ~/Desktop/某张照片.jpgxxd 是 Mac 自带的查看二进制内容的工具，-l 12 表示只看前 12 个字节。JPG 应该以 ffd8 ff 开头。
给表单加上传框
打开 app/admin/looks/look-form.tsx：在文件顶部加 import Image from "next/image";；在 LookDefaults 类型里加一行 imageUrl: string | null;；在“世界”下拉框后面插入：
<div>
<label htmlFor="image" className="block text-sm font-medium">
照片（JPG、PNG、WebP，不超过 4MB）
</label>
{look?.imageUrl && (
<Image src={look.imageUrl} alt="当前照片" width={120} height={160}
className="mt-2 rounded object-cover" />
)}
<input id="image" name="image" type="file"
accept="image/jpeg,image/png,image/webp"
className="mt-2 block w-full text-sm" />
{state.errors?.image && (
<p className="mt-1 text-sm text-red-600">{state.errors.image[0]}</p>
)}
</div>再到编辑页 app/admin/looks/[id]/edit/page.tsx，给传入的 look 对象加一行 imageUrl: look.imageUrl,。
改 Server Action
在 app/admin/looks/actions.ts 顶部加上第 6 节的导入和三个辅助函数，然后把三个 Action 中间的保存部分改成下面这样（开头的 requireAdmin、id 检查、文字校验保持不变）：
// createLook：文字校验通过之后
const image = readImage(formData);
let imageUrl: string | null = null;
if (image) {
const uploaded = await uploadImage(image);
if ("error" in uploaded) {
return { errors: { image: [uploaded.error] }, values };
}
imageUrl = uploaded.url;
}
await prisma.look.create({ data: { ...parsed.data, imageUrl } });
// updateLook：文字校验通过之后
const existing = await prisma.look.findUnique({
where: { id },
select: { imageUrl: true },
});
if (!existing) {
return { message: "这条 look 已经不存在了" };
}
let imageUrl = existing.imageUrl;
const image = readImage(formData);
if (image) {
const uploaded = await uploadImage(image);
if ("error" in uploaded) {
return { errors: { image: [uploaded.error] }, values };
}
imageUrl = uploaded.url;
}
await prisma.look.update({ where: { id }, data: { ...parsed.data, imageUrl } });
if (image && existing.imageUrl) {
await removeImage(existing.imageUrl); // 数据库已换成新图，再删旧图
}
// deleteLook：id 检查之后
const look = await prisma.look.delete({ where: { id } });
if (look.imageUrl) {
await removeImage(look.imageUrl);
}“先上传新图、再更新数据库、最后删旧图”的顺序你自己确认一遍，想清楚每一步失败时网站会是什么样。
前台卡片显示照片
DAY 42 的首页和世界详情页，是先把数据库查出的行转换成 lib/types.ts 里的 Look 类型，再交给 LookCard 显示的。所以要改三处：
lib/types.ts 的 Look 类型里加一行 imageUrl?: string | null。用问号表示可选，React 版留下来的旧数据没有这个字段也不会报错。app/page.tsx 的 rows.map 里加 imageUrl: row.imageUrl,；在 app/world/[slug]/page.tsx 传给 LookCard 的对象里加 imageUrl: look.imageUrl,。components/LookCard.tsx，顶部加 import Image from "next/image";，把第 7 节的图片代码放进卡片最上面，其中的 look 就是组件收到的那个 prop。测试四种情况
echo "not an image" > ~/Desktop/fake.jpg，看到“只支持 JPG、PNG、WebP 格式的图片”。删除测试 look，提交
在后台删掉测试用的 look，确认 Blob 里对应的图片也没了。然后提交：
git status
git add -A
git commit -m "look 支持上传照片：Vercel Blob，服务端检查大小和格式"提交前确认列表里没有 .env.local 和 .vercel。
next.config.ts 里的 bodySizeLimit 没配，或者配了但没重启开发服务器。.env.local 里没有 Blob 的变量。通常是建存储时没勾 Development 环境。到存储的 Projects 标签页，点项目旁边的菜单，选 Update Project Connection 把 Development 勾上，再运行一次 vercel env pull，重启开发服务器。remotePatterns 没写对或没重启。核对错误信息里的域名，是不是以 .public.blob.vercel-storage.com 结尾。access: "public"。访问方式建好后不能改，删掉重建一个 Public 的。DATABASE_URL，它会被写进 .env.local，并且优先级比 .env 高。本地数据库地址只放在 .env，Vercel 的 Development 环境不要配 DATABASE_URL。为什么要在服务端限制文件的大小和类型？
浏览器端的限制（比如 accept 属性）只是方便正常用户，别人可以删掉属性或者用脚本直接调用 Server Action，完全绕过。服务端不限制的话，有人能上传超大文件占满存储、产生费用，或者上传网页、脚本等非图片文件，借你的存储地址传播恶意内容。而且文件名和浏览器报的 type 都能伪造，所以要在服务端读取文件开头的字节判断真实格式，同时检查字节数。
为什么数据库里只存图片网址，而不是把图片本身存进去？
数据库擅长存小而多的结构化数据，图片几 MB 一张，存进去会让数据库变大变慢，备份变重，每次展示还要经过服务器读出再发给浏览器。放在对象存储里，浏览器拿着网址直接从 Vercel 的网络取图，快而且不占服务器；数据库里一个网址就够用。
编辑 look 换照片时，代码的顺序是“上传新图、更新数据库、删除旧图”。如果改成“先删旧图、再上传新图、再更新数据库”，可能出什么问题？
如果删完旧图后上传失败或数据库更新失败，数据库里的 imageUrl 还指向那张已经被删掉的旧图，前台就会显示一张裂开的图。原来的顺序下，任何一步失败，最坏只是 Blob 里多一张没人用的图片，网站显示始终正常。
status 字段（PENDING、APPROVED、HIDDEN）表示审核状态，而不是把不想展示的提问删掉。DAY 43 到 45，你在 /ask 做好了粉丝提问箱：粉丝写下问题，存进 Question 表；页面下方“东哥回答过的”只列出状态是 APPROVED 的提问。但到目前为止，你没有任何办法把一条提问改成 APPROVED、也没法写回答，只能靠种子数据里那两条示例。今天补上这一环：在后台审核、写回答，这样提问箱才真正变成和粉丝的互动。
但不能粉丝一提交就挂到网站上。公开的输入框一定会收到各种内容：广告、骂人的话、留了手机号的私人信息、和你无关的推销。你的观众主要是女性，有人可能在提问里写下自己的烦恼和隐私，她未必希望被所有人看到。所以要有一道关：先审后发。粉丝提交的问题默认不公开，你在后台看过、写好回答、点了“通过”，才出现在前台。
这就像店门口的留言板，留言先投进一个带锁的信箱，你每天打开信箱，挑出合适的，写好回复，再贴到板上。
审核也是一种责任。提问箱挂在你的官网上，上面公开的每一句话，别人都会默认是你认可的。一条带脏话的提问被挂出来，损害的是你的账号形象；一条暴露了某个女生姓名和学校的提问被挂出来，可能给她带来真实的麻烦。所以审核时除了看“合不合适”，还要看“有没有别人的隐私”。遇到内容可以回答、但带了个人信息的，可以只回答问题本身，或者隐藏它，私下在平台上回复。
我们给每条提问一个 status（状态）字段，只有三种取值：
| 值 | 含义 | 前台是否显示 |
|---|---|---|
| PENDING | 待审核，粉丝刚提交，你还没处理 | 不显示 |
| APPROVED | 已通过，你同意公开 | 显示 |
| HIDDEN | 已隐藏，不想公开 | 不显示 |
状态之间可以来回切换：待审核可以通过或隐藏；已通过的也能改成隐藏（比如你后来觉得那条回答不妥）；隐藏的也能退回待审核重新考虑。
用一条提问的“一生”串起来看：周一晚上，一位粉丝在前台问“第一次玩滑板穿什么鞋”，这条记录以 PENDING 状态进了数据库，前台看不到。周二你打开后台的“待审核”，看到它，写好回答，点“通过”，状态变成 APPROVED，前台出现一问一答。一个月后你换了推荐的鞋款，觉得旧回答过时了，可以直接改回答；如果暂时不想让它出现，就点“隐藏”，它变成 HIDDEN，从前台消失，但数据还在，随时能再拿出来。整个过程中，这条记录一直是同一行，只有 status 和 answer 两个字段在变。
为什么不直接删掉不想展示的提问？至少有四个理由：
这种“不真删，只做标记”的做法有个名字，叫软删除。真正的删除只留给确实需要清除的情况，比如粉丝明确要求删掉她的留言。
DAY 42 建 Question 表时已经有 status 和 answer 两个字段。打开 prisma/schema.prisma 核对一下，今天只需要在 Question 模型里加一行索引（下面倒数第三行）：
dongge-web/prisma/schema.prisma（Question 部分）
enum QuestionStatus {
PENDING
APPROVED
HIDDEN
@@map("question_status")
}
model Question {
id Int @id @default(autoincrement())
content String
nickname String?
status QuestionStatus @default(PENDING)
answer String?
createdAt DateTime @default(now()) @map("created_at")
@@index([status, createdAt])
@@map("questions")
}enum 是“枚举”，规定这个字段只能取列出来的几个值，数据库层面就挡住了拼错的 "APROVED"。@default(PENDING) 保证新提问默认是待审核，即使提交代码里忘了写状态，也不会自动公开。这就是“默认拒绝”的思路。answer 后面的问号表示可以为空，还没回答时就是空。
最后一行 @@index([status, createdAt]) 是 DAY 41 学的索引：前台每次都按“状态是已通过、按时间倒序”查询，建一个这两列的组合索引，提问多了以后查询依然快。DAY 42 的 schema 里还没有这一行，今天加上并迁移。@map 和 @@map 是 DAY 42 定的规矩：代码里用驼峰命名，数据库里用下划线命名，保持不动就好。
也顺便检查 DAY 43 写的 app/ask/actions.ts：它创建记录时只写了 content 和 nickname，没有写 status，这是对的，让数据库用默认值。以后改这段代码时，也不要写成 status: "APPROVED"。
后台列表要能切换“只看待审核”“只看已通过”。筛选条件放在哪？放在网址里最方便：/admin/questions?status=PENDING。问号后面的部分叫查询参数。好处是：刷新页面筛选不丢；你可以把“待审核”这个网址收藏起来，每天点开就是要处理的内容。
在 Next.js 的页面组件里，查询参数通过 searchParams 拿到。和 params 一样，它在 Next.js 16 里是一个 Promise：
export default async function AdminQuestionsPage({
searchParams,
}: {
searchParams: Promise<{ status?: string | string[] }>;
}) {
const { status } = await searchParams;
const parsed = questionStatusSchema.safeParse(status);
const current = parsed.success ? parsed.data : undefined;
// current 是 "PENDING" | "APPROVED" | "HIDDEN" 或 undefined（全部）
}你可能会问：筛选为什么不像 DAY 29 那样用 useState 在客户端做？因为后台列表是服务端组件，数据在服务端查询。把筛选条件放进网址，服务端每次按网址里的条件查数据库，只把需要的那部分发给浏览器；用链接切换筛选，也不需要写任何客户端代码。提问多到几百条时，这比“全部发给浏览器再在客户端过滤”要省得多。
重点在中间两行：网址是用户可以随便改的，有人可能输入 ?status=HACKED 或者重复写两次 status（这时拿到的是数组）。所以先用 Zod 校验，只有是三个合法值之一才用来筛选，否则当作“全部”。这和校验表单一样：来自浏览器的一切都要先校验。
每种状态有多少条，用 Prisma 的 groupBy 一次查出来，相当于 SQL 的 GROUP BY：
const groups = await prisma.question.groupBy({
by: ["status"],
_count: { _all: true },
});
// 结果类似：[{ status: "PENDING", _count: { _all: 3 } }, { status: "APPROVED", _count: { _all: 12 } }]先在 lib/validation.ts 里加两条规则：
dongge-web/lib/validation.ts（新增部分）
export const questionStatusSchema = z.enum(["PENDING", "APPROVED", "HIDDEN"]);
export const answerSchema = z.object({
answer: z.string().trim().max(500, "回答最多 500 个字"),
});
export type AnswerFormState = {
error?: string;
saved?: boolean;
answer?: string;
};然后是两个 Action：
dongge-web/app/admin/questions/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { answerSchema, questionStatusSchema, type AnswerFormState } from "@/lib/validation";
function isValidId(id: number) {
return Number.isInteger(id) && id > 0;
}
export async function setQuestionStatus(id: number, status: string) {
await requireAdmin();
if (!isValidId(id)) throw new Error("提问 id 不对");
const parsed = questionStatusSchema.safeParse(status);
if (!parsed.success) throw new Error("状态不对");
await prisma.question.update({
where: { id },
data: { status: parsed.data },
});
revalidatePath("/", "layout");
}
export async function answerQuestion(
id: number,
_prev: AnswerFormState,
formData: FormData,
): Promise<AnswerFormState> {
await requireAdmin();
if (!isValidId(id)) return { error: "提问 id 不对" };
const raw = String(formData.get("answer") ?? "");
const parsed = answerSchema.safeParse({ answer: raw });
if (!parsed.success) {
return { error: parsed.error.issues[0]?.message ?? "回答格式不对", answer: raw };
}
// 空字符串存成 null，表示“还没回答”
const answer = parsed.data.answer === "" ? null : parsed.data.answer;
await prisma.question.update({ where: { id }, data: { answer } });
revalidatePath("/", "layout");
return { saved: true, answer: parsed.data.answer };
}几点说明：
setQuestionStatus 的第二个参数类型写的是 string，而不是那三个值。这是故意的：提醒自己这个值从浏览器来，可能是任何字符串，必须先过 questionStatusSchema 才能用。setQuestionStatus.bind(null, q.id, "APPROVED") 这样的方式绑定好 id 和目标状态，点哪个就改成哪个。bind 的第一个参数 null 是固定写法，后面的参数会按顺序“预先填进”函数的参数里。原来要两个参数的函数，绑了两个之后就变成不需要参数的函数，正好可以交给表单的 action。answerQuestion 配合 useActionState，返回值会显示在表单旁边：保存成功显示“已保存”，失败显示错误，并把你写的内容带回去，避免表单重置后丢失。null，前台就知道“这条还没回答”。有一个规则需要你自己决定：没写回答的提问，能不能通过？如果你希望前台只出现“有问有答”的内容，就在 setQuestionStatus 里，当目标状态是 APPROVED 时先查出这条提问，answer 为空就抛错或直接返回。这是业务规则，没有标准答案，你决定后自己写。
前台提问箱的查询要同时做两件事：只取已通过的；只取页面要用的几列。DAY 43 你在 app/ask/page.tsx 里已经这样写了，今天有了审核，它才真正开始把关。完整的写法是：
const approved = await prisma.question.findMany({
where: { status: "APPROVED" },
orderBy: { createdAt: "desc" },
take: 20,
select: {
id: true,
content: true,
nickname: true,
answer: true,
createdAt: true,
},
});where 保证待审核和隐藏的内容永远不会被查出来。注意这个条件对所有访客都一样，包括登录着的你：前台就是给粉丝看的样子，你想看全部就去后台。不要在前台写“如果是管理员就多显示一些”这样的逻辑，这类分支很容易写错，把本该隐藏的内容漏给别人。take: 20 只取最新 20 条，避免以后提问多了页面太长；以后需要看更早的，可以再做“加载更多”或分页。
select 看起来多余，毕竟 Question 表也没几列。但养成习惯很重要：以后你可能给提问加上“提交者 IP”“内部备注”这类字段，如果前台查询写的是“全部列”，这些字段就会跟着被查出来，一旦传进客户端组件，就会出现在浏览器里。只取需要的列，新加的敏感字段默认就不会外泄。这就是 Next.js 文档里说的“数据传输对象”思路：给页面的数据，只包含页面需要的部分。
技术做完了，内容才是关键。你的定位是“情绪价值产生器”，但文案规则是“说事情不说情话”：回答要具体、克制，说清一件事，不油腻。对比一下：
| 粉丝提问 | 不建议 | 建议 |
|---|---|---|
| 东哥打泰拳会受伤吗？ | 为了保护你，受点伤算什么。 | 会有小伤，比如小腿淤青。每次训练前我会缠手带、戴护齿，教练在旁边看着。 |
| 斯诺克穿马甲不热吗？ | 穿给你看，热也值得。 | 球房有空调，不热。马甲的作用是让衬衫不乱，俯身架杆时不会碰到球。 |
| 第一次玩滑板穿什么鞋？ | 穿什么都好看，因为是你。 | 选平底、鞋底厚一点的板鞋，比如 Vans 的经典款。跑鞋鞋底太软，踩板不稳。 |
好的回答让人感觉被认真对待：她问了一个具体的问题，你给了一个具体、有用的答案。情绪价值来自“被认真回应”，而不是甜言蜜语。
明天开始写测试，让电脑帮你检查这些规则有没有被不小心改坏。
核对 schema，加索引并迁移
打开 prisma/schema.prisma，对照第 3 节检查 Question 模型：有 QuestionStatus 枚举、@default(PENDING)、可空的 answer。然后在 @@map("questions") 上面加一行 @@index([status, createdAt])，运行：
cd ~/code/dongge-web
npx prisma migrate dev --name add-question-status-index
npx prisma generateprisma/migrations 里多了一个名字带 add-question-status-index 的文件夹。加校验规则
在 lib/validation.ts 里加上第 5 节的 questionStatusSchema、answerSchema 和 AnswerFormState。
自己写两个 Action
新建 app/admin/questions/actions.ts，照第 5 节写。requireAdmin、id 检查、状态校验这三处自己敲。然后决定“没回答能不能通过”，如果不能，在 setQuestionStatus 里加上判断。
让 Claude 写回答表单组件
回答表单是客户端组件，属于样板代码。参考结果：
dongge-web/app/admin/questions/answer-form.tsx
"use client";
import { useActionState } from "react";
import type { AnswerFormState } from "@/lib/validation";
type Props = {
questionId: number;
action: (state: AnswerFormState, formData: FormData) => Promise<AnswerFormState>;
defaultAnswer: string;
};
export function AnswerForm({ questionId, action, defaultAnswer }: Props) {
const [state, formAction, pending] = useActionState(action, {});
const inputId = `answer-${questionId}`;
return (
<form action={formAction} className="mt-3 space-y-2">
<label htmlFor={inputId} className="block text-sm font-medium">东哥的回答</label>
<textarea id={inputId} name="answer" rows={3}
defaultValue={state.answer ?? defaultAnswer}
className="w-full rounded border px-3 py-2 text-sm" />
<div className="flex items-center gap-3">
<button type="submit" disabled={pending}
className="rounded bg-black px-3 py-1 text-sm text-white disabled:opacity-50">
{pending ? "保存中…" : "保存回答"}
</button>
{state.saved && <span className="text-sm text-green-700">已保存</span>}
{state.error && <span className="text-sm text-red-600">{state.error}</span>}
</div>
</form>
);
}一页会有很多条提问，每个输入框的 id 必须不同，所以用 answer- 加提问 id 拼出来。
写后台提问列表页
dongge-web/app/admin/questions/page.tsx
import Link from "next/link";
import { requireAdmin } from "@/lib/admin";
import prisma from "@/lib/prisma";
import { formatDate } from "@/lib/format";
import { questionStatusSchema } from "@/lib/validation";
import { answerQuestion, setQuestionStatus } from "./actions";
import { AnswerForm } from "./answer-form";
const STATUS_TEXT = { PENDING: "待审核", APPROVED: "已通过", HIDDEN: "已隐藏" } as const;
const TABS = ["PENDING", "APPROVED", "HIDDEN"] as const;
export default async function AdminQuestionsPage({
searchParams,
}: {
searchParams: Promise<{ status?: string | string[] }>;
}) {
await requireAdmin();
const { status } = await searchParams;
// 网址里的 status 谁都能改，先校验；不合法就当作“全部”
const parsed = questionStatusSchema.safeParse(status);
const current = parsed.success ? parsed.data : undefined;
const [questions, groups] = await Promise.all([
prisma.question.findMany({
where: current ? { status: current } : {},
orderBy: { createdAt: "desc" },
}),
prisma.question.groupBy({ by: ["status"], _count: { _all: true } }),
]);
const countOf = (s: string) => groups.find((g) => g.status === s)?._count._all ?? 0;
const total = groups.reduce((sum, g) => sum + g._count._all, 0);
return (
<div>
<h1 className="text-2xl font-bold">提问箱</h1>
<nav className="mt-4 flex flex-wrap gap-2 text-sm">
<Link href="/admin/questions"
className={`rounded border px-3 py-1 ${!current ? "bg-black text-white" : "bg-white"}`}>
全部 {total}
</Link>
{TABS.map((s) => (
<Link key={s} href={`/admin/questions?status=${s}`}
className={`rounded border px-3 py-1 ${current === s ? "bg-black text-white" : "bg-white"}`}>
{STATUS_TEXT[s]} {countOf(s)}
</Link>
))}
</nav>
{questions.length === 0 ? (
<p className="mt-8 text-neutral-500">这里没有提问。</p>
) : (
<ul className="mt-6 space-y-4">
{questions.map((q) => (
<li key={q.id} className="rounded-lg border bg-white p-4">
<div className="flex items-center justify-between text-sm text-neutral-500">
<span>{q.nickname ?? "匿名"} · {formatDate(q.createdAt)}</span>
<span>{STATUS_TEXT[q.status]}</span>
</div>
<p className="mt-2">{q.content}</p>
<AnswerForm
questionId={q.id}
action={answerQuestion.bind(null, q.id)}
defaultAnswer={q.answer ?? ""}
/>
<div className="mt-3 flex gap-2 text-sm">
{q.status !== "APPROVED" && (
<form action={setQuestionStatus.bind(null, q.id, "APPROVED")}>
<button type="submit" className="rounded border px-3 py-1">通过</button>
</form>
)}
{q.status !== "HIDDEN" && (
<form action={setQuestionStatus.bind(null, q.id, "HIDDEN")}>
<button type="submit" className="rounded border px-3 py-1">隐藏</button>
</form>
)}
{q.status !== "PENDING" && (
<form action={setQuestionStatus.bind(null, q.id, "PENDING")}>
<button type="submit" className="rounded border px-3 py-1">退回待审核</button>
</form>
)}
</div>
</li>
))}
</ul>
)}
</div>
);
}粉丝提问的内容直接用 {q.content} 显示，React 会自动转义，就算里面写了 <script> 也只会显示成文字（DAY 45 学过）。如果你的 status 字段是普通字符串而不是枚举，STATUS_TEXT[q.status] 可能会报类型错误，把它改成 STATUS_TEXT[q.status as keyof typeof STATUS_TEXT]。
核对前台提问箱
打开 DAY 43 写的 app/ask/page.tsx，找到查询 answered 的那一段，对照第 6 节检查：where 是否只取 APPROVED，select 是否只取了页面需要的几列。然后在查询里加上 take: 20，只显示最新 20 条。
DAY 43 的页面只在有回答时才显示“东哥：”那一行。如果你在第 3 步决定“允许没回答的提问通过”，可以把那一段改成没回答时显示一句“还没回答，过两天再来看。”：
<p className="mt-3 text-gray-700">
{question.answer ? `东哥：${question.answer}` : "还没回答，过两天再来看。"}
</p>完整走一遍审核流程
运行 npm run dev，按顺序做：
/ask 提交两个问题，比如“东哥打泰拳会受伤吗？”和一条故意写的广告。试试乱改网址
在后台地址栏输入 /admin/questions?status=HACKED 和 /admin/questions?status=PENDING&status=HIDDEN。
写三条真实回答
从真实粉丝留言里（或者你在小红书、TikTok 评论区常被问到的问题里）挑三条，按第 7 节的分寸写回答并通过。写完读一遍：有没有空泛的形容词？有没有说清一件具体的事？
审查并提交
用下方第 2 条提示词让 Claude 检查今天的改动，然后提交：
git add -A
git commit -m "提问箱审核：状态筛选、写回答，前台只显示已通过"where 是不是写成了别的状态，Action 里有没有 revalidatePath，以及你看的是不是正确的页面文件。status: "APPROVED"，或者前台查询漏了 where。删掉前者、补上后者。groupBy 报类型错误：检查 by 是不是数组 ["status"]，_count 是不是写成 { _all: true }。改完 schema 后记得 npx prisma generate。AnswerForm 是独立组件，互不影响；如果出现这种情况，通常是 textarea 的 id 重复了，检查 questionId 是否传对。为什么不直接删掉不想展示的提问，而是用状态字段？
删除是永久的，状态可以随时改回来，误操作代价小；保留下来的记录可以作为骚扰内容的证据，也能帮你识别同一个人反复发的内容；以后做统计（每周收到多少、隐藏了多少）需要完整的数据。用状态字段只是“做标记”，这叫软删除。真正删除只留给确实要清除的情况，比如粉丝要求删掉她的留言。
前台提问箱的查询为什么要用 select 只取几列，而不是取整行？
页面只需要内容、昵称、回答和时间。只取需要的列，以后表里新增的内部字段（比如 IP、备注）默认不会被查出来，也就不会被传进客户端组件、出现在浏览器里。这是“只给页面需要的数据”的习惯，能防止将来无意中泄露信息。
如果有人把后台网址改成 /admin/questions?status=ANYTHING，你的页面会怎样？这说明了什么原则？
页面先用 questionStatusSchema.safeParse 校验，ANYTHING 不是三个合法值之一，校验失败，current 为 undefined，页面按“全部”显示，不会报错，也不会把奇怪的值传进数据库查询。原则是：来自浏览器的所有输入，包括网址参数、表单、绑定的参数，都要先校验再使用。
describe、test、expect，用 npm test 运行。过去五天，你的后台一天比一天复杂：登录、权限、增删改查、图片、审核。每次改代码，你都手动点一遍来确认没坏。问题是，功能越多，要点的地方越多，总有一天你会漏点一个。比如今天为了改标题长度动了 lookSchema，却没发现测试小游戏的计分也被你顺手改坏了，直到粉丝在评论区说“怎么谁测都是绅士”。
测试就是用代码去检查代码：写一段程序，给你的函数一个输入，检查它的输出是不是你预期的。写一次，以后每次改完代码，一条命令就能把所有检查跑一遍，几秒钟告诉你哪里坏了。
打个比方：拳手赛前要过秤。体重是不是在级别内，不靠自己感觉，靠秤。测试就是你代码的秤，每次上场前过一遍，数字不对就知道哪里出了问题，而不是上了台才发现。
测试最大的价值在未来：它防止你以后不小心改坏现在能用的东西。这种“改了 A 却弄坏了 B”的问题叫回归，防回归是写测试的首要目的。
写测试当然要花时间，不可能每一行代码都测。先测哪些？按这个顺序挑：一是出错后果严重的，比如校验规则，它一旦失效，垃圾数据就进了数据库；二是逻辑绕、容易写错的，比如同分怎么算、跨天怎么显示；三是你以后大概率还会改的。像“按钮是黑色还是灰色”这种一眼就能看出来的，不值得写测试。
测试分好几种。今天学的是单元测试：只测一个小单元，通常是一个函数，不开浏览器、不连数据库，跑得飞快。明天学的端到端测试，才是打开真浏览器、点真按钮。
单元测试最适合测纯函数。纯函数有两个特点：
第二条里说的“别的事”，在编程里叫副作用：函数除了返回值之外对外界造成的影响，比如往数据库写一行、往 Blob 传一张图、弹一个确认框。副作用本身没有错，网站总要保存数据；但带副作用的函数很难测，因为每测一次都会真的改动外界。所以常见的做法是：把“算”的部分和“做”的部分分开，算的部分写成纯函数单独测。
用这个标准看看 dongge-web 里的函数：
| 函数 | 是纯函数吗 | 原因 |
|---|---|---|
| scoreQuiz（计分） | 是 | 给一组答案，算出一个世界 |
| formatDate（日期格式） | 是 | 时间作为参数传进来，不自己读当前时间 |
| lookSchema.safeParse（校验） | 是 | 给一个对象，返回通过或错误 |
| detectImageType（图片格式） | 是 | 给一串字节，返回格式 |
| createLook（新建 look） | 不是 | 要读会话、写数据库、上传文件 |
你会发现，前几天我们有意把逻辑抽成了独立的小函数，比如 formatDate 把时区作为参数，而不是在函数里读服务器时间。这样做的好处今天就兑现了：它们都很好测。像 createLook 这种牵扯数据库和登录的，交给明天的端到端测试。
Vitest 是一个测试框架，负责找到测试文件、运行它们、汇报结果。它和你 DAY 23 用过的 Vite 是一家，配置简单、速度快。文件名里带 .test. 的，就会被它当作测试文件。
一个最小的测试长这样：
import { describe, expect, test } from "vitest";
import { formatDate } from "./format";
describe("formatDate 日期格式", () => {
test("默认按 UTC+8 显示成“几月几日 周几”", () => {
const input = new Date("2026-10-01T04:00:00Z");
const result = formatDate(input);
expect(result).toBe("10月1日 周四");
});
});逐行看：
describe 把相关的测试归成一组，第一个参数是组名，会显示在结果里。test 定义一个测试，第一个参数是测试名。用中文写清楚“在什么情况下，应该得到什么”，失败时一眼就知道是哪条规则坏了。expect(实际值).toBe(期望值) 是断言：如果两者不相等，这个测试就失败。运行后，Vitest 会列出每个测试文件和其中每个测试，通过的前面打勾，失败的打叉，最后汇总一行：几个文件、几个测试通过、几个失败、用了多少毫秒。失败时它会把失败的测试名、期望值和实际值、出错代码所在的文件和行号都打印出来，这些信息足够你定位问题，不用去猜。
今天会用到的几个断言：
toBe(值)：严格相等，适合字符串、数字、布尔值。toEqual(对象)：比较对象或数组的内容是否一样。toThrow(文字)：检查函数会抛出错误，而且错误信息包含这段文字。要把调用包在一个箭头函数里：expect(() => scoreQuiz([])).toThrow()，否则错误在 expect 之前就抛出来了。好消息是，DAY 39 迁移测试小游戏时，你已经把计分逻辑放在了 lib/quiz.ts 里的 scoreQuiz(answers: World[]): World，游戏组件 components/Quiz.tsx 只负责调用它。计分和界面分开，这个函数就是纯函数，可以直接测。这就是当初把它单独放一个文件的回报。
测试之前，先把规则定清楚。DAY 18 的验收题问过你：两个世界同分时怎么办？现在的游戏有 3 道题，每道题投一个世界，所以只可能出现“3 比 0”“2 比 1”或者“1 比 1 比 1”三种局面。最后一种就是同分。今天把规则写明白：同分时，看最后一道题选的是哪个世界。理由是最后一题通常凭直觉选，更能代表当下的心情。你也可以定别的规则，重要的是规则明确、可以测试。
打开 lib/quiz.ts，对照下面的参考实现检查你 DAY 39 写的 scoreQuiz。如果你的写法不同但规则一致，保留你的；如果你没处理同分，或者同分时的结果说不清，按这个思路改。文件里原有的题目数据 quizQuestions 不用动。
dongge-web/lib/quiz.ts（scoreQuiz 部分）
import type { World } from "@/lib/types";
const WORLD_ORDER: World[] = ["gentleman", "street", "thai"];
/**
* 每道题的答案对应一个世界，选得最多的世界胜出。
* 同分时，看最后一道题选的世界；它在并列名单里就选它。
*/
export function scoreQuiz(answers: World[]): World {
if (answers.length === 0) {
throw new Error("至少要回答一道题");
}
const counts: Record<World, number> = { gentleman: 0, street: 0, thai: 0 };
for (const answer of answers) {
counts[answer] += 1;
}
const max = Math.max(...Object.values(counts));
const tied = WORLD_ORDER.filter((world) => counts[world] === max);
if (tied.length === 1) {
return tied[0];
}
const lastTied = [...answers].reverse().find((answer) => tied.includes(answer));
return lastTied ?? tied[0];
}思路分四步：没有答案直接报错；数出每个世界被选了几次；找出最高票，看有几个世界并列；只有一个就返回它，有并列就从最后一题往前找，第一个落在并列名单里的就是结果。[...answers].reverse() 先复制一份再反转，不改原数组，保持“纯”。World 是 DAY 38 在 lib/types.ts 里定义的类型，只能是三个世界之一。
如果你改动了 scoreQuiz，改完在浏览器里把游戏完整玩两遍，确认结果页正常。这种“功能不变，只调整代码内部写法”的修改叫重构。有了今天的测试，以后重构就不用每次都手动玩一遍了。
DAY 48 你写的 formatDate 带了一个 utcOffsetHours 参数。测试它时，输入要用带 Z 的时间字符串，比如 "2026-10-01T04:00:00Z"。末尾的 Z 表示这是 UTC 时间，无论测试在你的 Mac 上跑还是在 GitHub 的服务器上跑，它代表的都是同一个时刻。如果写成不带 Z 的 "2026-10-01 12:00"，JavaScript 会按运行测试那台电脑的时区理解，同一个测试在不同电脑上结果不同，这种测试叫“不稳定的测试”，比没有测试还烦人。
日期函数最容易出错的地方是“跨天”：UTC 时间还是 9 月 30 日晚上 8 点，在 UTC+8 已经是 10 月 1 日凌晨 4 点。专门给这种边界写一个测试，比测十个普通日期更有价值。
test("UTC 时间还是 9 月 30 日晚上，在 UTC+8 已经是 10 月 1 日", () => {
expect(formatDate(new Date("2026-09-30T20:00:00Z"))).toBe("10月1日 周四");
});校验规则也是纯函数：safeParse 给一个对象，返回一个结果。测试时检查两样东西：success 是 true 还是 false；失败时第一条错误信息是不是你写的那句中文。
test("标题只有空格时不通过，提示“标题不能为空”", () => {
const result = lookSchema.safeParse({ ...validLook, title: " " });
expect(result.success).toBe(false);
expect(result.error?.issues[0].message).toBe("标题不能为空");
});validLook 是在文件顶部准备好的一份合法数据，每个测试用展开运算符 ...（DAY 17 学过）复制一份，只改想测的那一个字段。这样每个测试只测一件事，失败了立刻知道是哪个字段的规则出了问题。result.error?. 里的问号是可选链：通过时没有 error，不会因为读不存在的属性而报错。
测试错误信息而不只是测 success，是因为错误信息是用户看得到的文字。哪天有人把“标题不能为空”误改成了英文，测试会立刻提醒你。
还要留意 worldId 这种“转换”规则：表单传来的是字符串 "2"，校验通过后变成数字 2。测试里同时检查 result.data.worldId 等于数字 2，就能确认转换真的发生了。如果哪天有人删掉了 coerce，数据库那一步才会报错，而测试能提前在这里拦住。DAY 49 写的 detectImageType 也是纯函数，今天时间充裕的话，可以用 new Uint8Array([0xff, 0xd8, 0xff]) 这样的假字节给它加几个测试，作为加练。
明天你会写另一种测试：打开真实的浏览器，像粉丝和你一样在网站上点来点去。
确认 Node 版本，安装 Vitest
当前版本的 Vitest 要求 Node.js 22.12 或更高。先看一眼：
cd ~/code/dongge-web
node -v
npm install -D vitest vite-tsconfig-paths如果 node -v 显示低于 v22.12，先用 DAY 01 装 Node 的方法升级到当前的 LTS 版本。vite-tsconfig-paths 让测试也认识 @/ 开头的导入路径。安装命令以 Vitest 和 Next.js 官方文档为准。
写 Vitest 配置
dongge-web/vitest.config.mts
import { defineConfig } from "vitest/config";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
environment: "node",
include: ["**/*.test.ts"],
},
});environment: "node" 表示在 Node 环境里跑，我们测的都是纯函数，不需要模拟浏览器。include 只认 .test.ts 结尾的文件，明天 Playwright 的测试文件用 .spec.ts 结尾，两者互不干扰。
加 npm 脚本
打开 package.json，在 scripts 里加两行（其他行保持不变）：
"test": "vitest run",
"test:watch": "vitest"vitest run 跑一遍就结束，适合提交前和明后天的自动化检查；vitest 不带 run 是“监视模式”，你一保存文件它就自动重跑。
检查 scoreQuiz 的同分规则
打开 lib/quiz.ts，对照第 4 节检查你 DAY 39 写的 scoreQuiz：空数组怎么处理？三个世界各一票时返回哪个？这是业务逻辑，改动由你自己写。改完运行 npm run dev，打开 /quiz 完整玩两遍，其中一遍故意三题选三个不同的世界。
写计分测试（5 个）
dongge-web/lib/quiz.test.ts
import { describe, expect, test } from "vitest";
import { scoreQuiz } from "./quiz";
describe("scoreQuiz 计分", () => {
test("街头选得最多时，结果是街头", () => {
expect(scoreQuiz(["street", "gentleman", "street"])).toBe("street");
});
test("三题全选泰风，结果是泰风", () => {
expect(scoreQuiz(["thai", "thai", "thai"])).toBe("thai");
});
test("三个世界各一票时，最后一题选的那个世界胜出", () => {
expect(scoreQuiz(["gentleman", "street", "thai"])).toBe("thai");
});
test("同样各一票，顺序变了，结果也跟着变", () => {
expect(scoreQuiz(["thai", "street", "gentleman"])).toBe("gentleman");
});
test("一道题都没答时直接报错", () => {
expect(() => scoreQuiz([])).toThrow("至少要回答一道题");
});
});如果你的同分规则和参考实现不同，第 3、4 个测试按你的规则改期望值。scoreQuiz 本身不限定题数，以后游戏加到 6 道题，这些测试照样有效；到时候可以再补一个“两个世界 3 比 3”的测试。
写日期测试（3 个）
dongge-web/lib/format.test.ts
import { describe, expect, test } from "vitest";
import { formatDate } from "./format";
describe("formatDate 日期格式", () => {
test("默认按 UTC+8 显示成“几月几日 周几”", () => {
expect(formatDate(new Date("2026-10-01T04:00:00Z"))).toBe("10月1日 周四");
});
test("UTC 时间还是 9 月 30 日晚上，在 UTC+8 已经是 10 月 1 日", () => {
expect(formatDate(new Date("2026-09-30T20:00:00Z"))).toBe("10月1日 周四");
});
test("传入 7 就按泰国时间显示", () => {
expect(formatDate(new Date("2026-09-30T16:30:00Z"), 7)).toBe("9月30日 周三");
});
});自己在纸上算一遍第 3 个：UTC 16:30 加 7 小时是 23:30，还在 9 月 30 日；如果按 UTC+8 就是 10 月 1 日 0:30 了。
写校验测试（7 个）
下面的 questionSchema 部分假设你 DAY 44 给提问箱写的 Zod 规则叫 questionSchema，规则是“问题去掉空格后不能为空、最多 200 个字，昵称最多 20 个字”（和 DAY 43 表单上的限制一致）。打开你的规则对照：名字、位置、数字不同，就改测试里的导入路径和数字。
dongge-web/lib/validation.test.ts
import { describe, expect, test } from "vitest";
import { lookSchema, questionSchema } from "./validation";
const validLook = {
title: "街头 BMX 日常",
description: "Baggy 裤配 Vans，适合周末去滑板场。",
worldId: "2",
published: true,
};
describe("lookSchema", () => {
test("合法输入能通过，标题两边的空格被去掉，worldId 变成数字", () => {
const result = lookSchema.safeParse({ ...validLook, title: " 街头 BMX 日常 " });
expect(result.success).toBe(true);
expect(result.data?.title).toBe("街头 BMX 日常");
expect(result.data?.worldId).toBe(2);
});
test("标题只有空格时不通过，提示“标题不能为空”", () => {
const result = lookSchema.safeParse({ ...validLook, title: " " });
expect(result.success).toBe(false);
expect(result.error?.issues[0].message).toBe("标题不能为空");
});
test("标题正好 40 个字能通过，41 个字不行", () => {
expect(lookSchema.safeParse({ ...validLook, title: "绅".repeat(40) }).success).toBe(true);
expect(lookSchema.safeParse({ ...validLook, title: "绅".repeat(41) }).success).toBe(false);
});
test("没选世界时不通过，提示“请选择一个世界”", () => {
const result = lookSchema.safeParse({ ...validLook, worldId: "" });
expect(result.success).toBe(false);
expect(result.error?.issues[0].message).toBe("请选择一个世界");
});
});
describe("questionSchema（数字按你 DAY 44 的规则改）", () => {
test("正常的问题和昵称能通过", () => {
expect(
questionSchema.safeParse({ content: "东哥，打斯诺克穿马甲会不会热？", nickname: "小鹿" }).success,
).toBe(true);
});
test("问题只有空格时不通过", () => {
expect(questionSchema.safeParse({ content: " ", nickname: "小鹿" }).success).toBe(false);
});
test("问题超过 200 个字不通过", () => {
expect(questionSchema.safeParse({ content: "问".repeat(201), nickname: "小鹿" }).success).toBe(false);
});
});运行全部测试
npm test故意改坏，读失败输出
打开 lib/validation.ts，把标题的 max(40 改成 max(50，保存，再运行 npm test。你会看到一个测试变红，输出里有测试名“标题正好 40 个字能通过，41 个字不行”，有 Expected（期望）和 Received（实际），还有出错的那一行代码位置。读懂它，然后改回 40，再跑一次，全部变绿。
再试一次：把 lib/quiz.ts 里的 reverse() 删掉，看哪两个测试失败，想想为什么，再改回来。
体验监视模式，提交
运行 npm run test:watch，随便改一下 format.ts 里的周几数组再保存，看测试自动重跑。按 q 退出。最后提交：
git add -A
git commit -m "加入 Vitest：计分、日期格式、校验规则共 15 个单元测试"node_modules 重新 npm install。@/lib/... 模块：vitest.config.mts 里没加 tsconfigPaths() 插件，或者配置文件名写错了。Z，或者函数里用了 getDate() 而不是 getUTCDate()。toThrow 的测试直接报错，而不是通过：你写成了 expect(scoreQuiz([])).toThrow()。要包一层箭头函数：expect(() => scoreQuiz([])).toThrow()。test 脚本写成了 vitest（监视模式）。改成 vitest run，或者按 q 退出。你写的测试里，哪一个最能防止以后不小心改坏东西？
没有唯一答案，重点是理由。例如“三个世界各一票时，最后一题选的那个世界胜出”：同分规则是最容易在改计分代码时被悄悄破坏的地方，而且手动玩游戏时很少会特意去玩出同分，靠人工几乎发现不了，测试却每次都会检查。又如“标题正好 40 个字能通过，41 个字不行”：它守住边界，谁动了长度限制都会被发现。好的回答要说清这个测试守住了哪条规则，以及为什么靠手动点很难发现这条规则被改坏。
为什么 createLook 这种 Server Action 不适合用今天的方法写单元测试？
它不是纯函数：要读取登录会话、连接数据库、可能还要上传图片，结果取决于外部环境。单元测试要快、要稳定、不依赖外部服务。这类“把很多东西串起来”的功能，更适合用端到端测试从浏览器里整体验证；而它里面的纯逻辑（比如校验规则）已经被抽出来单独测了。
15 个测试全部通过，能说明代码没有 bug 吗？
不能。测试只能证明“你想到的那些情况”是对的，没想到的情况照样可能出错。比如游戏以后加到 6 道题，出现两个世界 3 比 3 的情况，你现在的测试就没覆盖到。测试的作用是给已知规则上保险、防止回归，而不是证明没有 bug。发现新 bug 时，先写一个能重现它的测试，再修代码，让测试集越来越完整。
npm init playwright@latest 装好 Playwright，并用 webServer 配置让它自动启动网站。昨天的单元测试只检查一个个小函数：计分对不对、日期格式对不对。但一个网站能用，还需要很多零件配合：页面能打开、表单能填、按钮能点、Server Action 能收到数据、数据库能保存、页面能刷新出新内容。每个零件都对，拼起来也可能不对，比如按钮文字改了、表单字段名写错了、忘了 revalidatePath。
端到端测试（End-to-End，简称 E2E）就是从最前端（浏览器）一直测到最后端（数据库）：打开一个真实的浏览器，像真人一样访问网址、填表、点击，然后检查页面上有没有出现该出现的东西。
打个比方：单元测试是拍视频前分别检查灯光、收音、机位；端到端测试是完整彩排一遍，从你走进画面到说完最后一句。零件检查快而细，彩排慢但最接近真实。
| 单元测试（Vitest） | 端到端测试（Playwright） | |
|---|---|---|
| 测什么 | 一个函数的输入输出 | 一条完整的用户流程 |
| 要不要浏览器、数据库 | 不要 | 都要 |
| 速度 | 几毫秒一个 | 几秒一个 |
| 出错时 | 直接指出哪个函数哪条规则 | 知道哪条流程断了，要再找原因 |
| 适合写多少 | 多，规则都可以测 | 少，只测最重要的几条路 |
所以两者搭配：大量小而快的单元测试守住规则，少量端到端测试守住最关键的几条路。今天就写三条：粉丝能提问、你能登录、你发布的 look 前台能看到。挑这三条，是因为它们分别对应网站的三种角色和三件最要紧的事：粉丝能说话、只有你能进后台、你发的内容能被看见。任何一条断了，网站就等于坏了。
什么时候跑？单元测试很快，每次保存都可以跑；端到端测试要启动网站、开浏览器，一轮要一两分钟，适合在提交代码前、或者改完一个较大的功能后跑一次。
Playwright 是微软开源的浏览器自动化工具。它能控制 Chromium（Chrome 的内核）、Firefox、WebKit（Safari 的内核）三种浏览器。你写的测试代码会告诉它“打开这个网址”“在这个输入框里填字”“点这个按钮”“检查页面上有没有这段文字”。
一条测试由几种东西组成：
page：一个浏览器标签页。await page.goto("/login") 打开登录页。page.getByLabel("邮箱") 找 label 是“邮箱”的输入框，page.getByRole("button", { name: "登录" }) 找文字是“登录”的按钮，page.getByText("收到") 找包含这段文字的元素。fill 填字、click 点击、check 勾选复选框、selectOption 选下拉框。await expect(page).toHaveURL(/\/admin$/) 检查当前网址；await expect(locator).toBeVisible() 检查元素出现在页面上。还记得 DAY 05 的验收题“为什么 input 要配 label”吗？今天是答案的另一半：getByLabel 就是靠 label 的文字找到输入框的。label 写得规范，测试就好写；读屏软件能找到的元素，测试也能找到。这也是为什么前几天的表单都要求 label 用固定的文字。
Playwright 有一个让新手省心的特性：自动等待。点击按钮后页面要等服务器返回，你不用写“等两秒”，expect(...).toBeVisible() 会自动反复检查，直到元素出现或超时（默认 5 秒）。
还有一个帮你起步的工具：npx playwright codegen localhost:3000。它会打开一个浏览器，你在里面怎么点，它就在旁边的窗口里实时生成对应的测试代码。刚开始不知道定位器怎么写时，可以用它录一遍，再把生成的代码整理进测试文件。录出来的代码要逐行读懂再用，不要原样照搬，这和读 Claude 写的代码是一个道理。
这是今天最重要的一节。端到端测试是真的在操作网站：提交提问会真的往数据库写一条，发布 look 会真的新建一条。如果测试连的是你平时开发用的数据库，每跑一次就多几条“E2E 测试”的垃圾数据；更糟的是，如果哪天测试写错了，删错了东西，删的就是你的真实内容。
所以规则是：测试用自己的数据库，测试用自己的账号。对新手来说，最省事的办法是 Neon 的分支（branch）功能。
Neon 的分支和 Git 的分支是一个思路：从现有的数据库“复制”出一份独立的副本，表结构和数据都一样，之后两边各改各的，互不影响。复制几乎是瞬间完成的，免费计划就能用。你 DAY 40 在 Neon 控制台建项目时，它自动创建的根分支叫 production，你一直在它上面开发。今天从它复制出一个叫 e2e 的分支，专门给测试用。
准备测试数据库还有别的办法，比如在自己电脑上用 Docker 跑一个 PostgreSQL，或者建一个只有表结构、没有数据的“空分支”再自己灌数据。它们更“干净”，但对你来说步骤多、容易卡住。复制一个带现有数据的分支，世界、look 都是现成的，测试一上来就能用，是新手最容易走通的路。等 e2e 分支里的测试数据积累多了、变乱了，Neon 的分支页面有“从父分支重置”（Reset from parent）的功能，一键恢复成和 production 一样的状态。重置后记得重新创建测试管理员。
测试账号怎么办？DAY 47 的授权规则是“邮箱等于 ADMIN_EMAIL 的才是管理员”，这个邮箱从环境变量读。所以测试时只要让网站读到另一套环境变量就行：
dongge-web/.env.e2e
DATABASE_URL=e2e 分支的连接地址
BETTER_AUTH_SECRET=随便生成一个测试用的
BETTER_AUTH_URL=http://localhost:3000
ADMIN_EMAIL=e2e-admin@example.com
E2E_ADMIN_PASSWORD=给测试账号设的密码测试时网站连 e2e 分支，管理员是 e2e-admin@example.com，你自己的真实账号和密码完全不出现在测试里。测试账号用 DAY 46 写的 create-admin.ts 脚本在 e2e 分支里创建。这个文件名以 .env 开头，会被 .gitignore 里的 .env* 规则忽略，不会提交。
Playwright 的配置文件决定：测试放在哪、用什么浏览器、怎么启动网站。
dongge-web/playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
import { config } from "dotenv";
// 读取测试专用的环境变量：连 Neon 的 e2e 分支，用测试管理员账号
config({ path: ".env.e2e", override: true });
if (!process.env.E2E_ADMIN_PASSWORD) {
throw new Error("缺少 .env.e2e 或其中的 E2E_ADMIN_PASSWORD");
}
export default defineConfig({
testDir: "./e2e",
workers: 1,
reporter: "html",
use: {
baseURL: "http://localhost:3000",
trace: "retain-on-failure",
screenshot: "only-on-failure",
},
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
],
webServer: {
command: "npm run dev",
url: "http://localhost:3000",
reuseExistingServer: false,
timeout: 120_000,
},
});逐项解释：
dotenv 读取 .env.e2e，把测试数据库地址等变量放进当前进程。override: true 表示覆盖已有的同名变量。下面的检查保证忘了建这个文件时立刻报错，而不是悄悄连到别的数据库。testDir: "./e2e"：测试文件放在项目根目录的 e2e 文件夹。workers: 1：一次只跑一个测试。几条测试共用一个数据库，排队跑最不容易互相干扰。baseURL：之后写 page.goto("/login") 就会自动拼成完整网址。trace 和 screenshot：测试失败时保留操作记录和截图，方便查原因。projects：只用 Chromium 一种浏览器，够用且快。以后想测 Safari 再加 WebKit。webServer：跑测试前，Playwright 自己运行 npm run dev 启动网站，等 3000 端口能访问了再开始测。启动的网站会继承上面读进来的环境变量，所以连的是 e2e 分支。Next.js 读取 .env 文件时，不会覆盖已经存在的同名变量，因此你 .env 里的开发库地址不会生效。reuseExistingServer: false：如果 3000 端口已经有网站在跑（比如你自己开着的 npm run dev，连的是开发库），Playwright 会报错停下，而不是直接拿来测。这是一道保险，防止测试误连开发库。从最简单的开始，不需要登录：
dongge-web/e2e/question.spec.ts
import { expect, test } from "@playwright/test";
test("粉丝可以提交提问，并看到感谢提示", async ({ page }) => {
await page.goto("/ask");
await page.getByLabel("你的问题").fill(`E2E 测试：泰拳短裤怎么选尺码？${Date.now()}`);
await page.getByRole("button", { name: "投进提问箱" }).click();
await expect(page.getByText("收到")).toBeVisible();
});async ({ page }) 是 Playwright 交给你的一个新标签页，每条测试都是干净的，没有 Cookie、没有登录。问题内容后面加 Date.now()（当前时间的毫秒数），让每次提交的内容都不一样，方便在后台区分。
/ask、label“你的问题”、按钮“投进提问箱”都来自 DAY 43 写的 app/ask/page.tsx。最后一行检查的“收到”是假设的文字：DAY 44 你给提问箱加了提交成功的提示，打开页面看看你的提示语实际写的是什么，把 getByText 里的文字换成其中一段。如果你后来改过 label 或按钮文字，也照着改。这正好也是一次检查：你的输入框有没有配 label？
后面两条测试都要登录，把登录步骤写成一个辅助函数，避免重复：
dongge-web/e2e/helpers.ts
import { expect, type Page } from "@playwright/test";
export async function loginAsAdmin(page: Page) {
await page.goto("/login");
await page.getByLabel("邮箱").fill(process.env.ADMIN_EMAIL!);
await page.getByLabel("密码").fill(process.env.E2E_ADMIN_PASSWORD!);
await page.getByRole("button", { name: "登录" }).click();
await expect(page).toHaveURL(/\/admin$/);
}process.env.ADMIN_EMAIL! 末尾的感叹号告诉 TypeScript“我保证这里有值”，因为配置文件里已经检查过了。/\/admin$/ 是正则表达式，意思是“网址以 /admin 结尾”。
dongge-web/e2e/admin-login.spec.ts
import { expect, test } from "@playwright/test";
import { loginAsAdmin } from "./helpers";
test("未登录会被带到登录页，登录后能进后台", async ({ page }) => {
await page.goto("/admin");
await expect(page).toHaveURL(/\/login$/);
await loginAsAdmin(page);
await expect(page.getByRole("heading", { name: "后台总览" })).toBeVisible();
});这条测试同时验证了 DAY 47 的两件事：未登录访问后台会被拦下；正确的账号能进去。以后谁改动了登录或权限代码，只要这条流程断了，测试就会变红。
这条最长，串起了 DAY 48 的整个后台流程，最后还要把自己制造的数据清理掉：
dongge-web/e2e/publish-look.spec.ts
import { expect, test } from "@playwright/test";
import { loginAsAdmin } from "./helpers";
test("在后台发布 look 后，前台首页能看到它", async ({ page }) => {
const title = `E2E 街头 look ${Date.now()}`;
await loginAsAdmin(page);
await page.goto("/admin/looks/new");
await page.getByLabel("标题").fill(title);
await page.getByLabel("描述").fill("Oversize 卫衣配 Vans，测试用。");
await page.getByLabel("世界").selectOption({ label: "街头" });
await page.getByLabel("发布到前台").check();
await page.getByRole("button", { name: "保存" }).click();
await expect(page).toHaveURL(/\/admin\/looks$/);
await page.goto("/");
await expect(page.getByText(title)).toBeVisible();
// 清理：回后台删掉这条，保持测试库干净
await page.goto("/admin/looks");
page.once("dialog", (dialog) => dialog.accept());
await page.getByRole("row", { name: title }).getByRole("button", { name: "删除" }).click();
await expect(page.getByText(title)).toHaveCount(0);
});几个新东西：
Date.now()，保证每次都是一个全新的、唯一的标题。这样检查“前台能看到它”时，不会被上次测试留下的同名 look 干扰。selectOption({ label: "街头" }) 按选项的文字选下拉框；check() 勾选复选框。page.once("dialog", ...) 提前告诉 Playwright：下一个弹出的对话框，点“确定”。要写在点删除之前。getByRole("row", { name: title }) 先找到表格里包含这个标题的那一行，再在这一行里找“删除”按钮，不会误删别的行。toHaveCount(0) 检查页面上已经找不到这个标题，确认删干净了。如果你的首页不显示全部 look（比如只显示每个世界的前几条），把 page.goto("/") 改成街头世界的详情页地址。
明天你会让这些检查在每次推送代码时自动运行。
在 Neon 创建 e2e 分支
打开 Neon 控制台，进入你的项目，左侧点 Branches，点 New branch。父分支（parent）选 production（如果你的根分支叫 main，就选 main），名字填 e2e，数据选项选包含当前数据的那一项，点 Create。
建好后点顶部的 Connect，在弹出框里把分支切换成 e2e，数据库选 neondb（和 DAY 42 一样，不是 practice），关掉 Connection pooling 开关，复制连接地址。
.env 里的不一样（主机名里的编号不同）。写 .env.e2e
在项目根目录新建 .env.e2e，内容照第 3 节。DATABASE_URL 填刚复制的 e2e 地址；BETTER_AUTH_SECRET 用 openssl rand -base64 32 再生成一个；E2E_ADMIN_PASSWORD 自己想一个 12 位以上的。然后确认它不会被提交：
cd ~/code/dongge-web
git check-ignore -v .env.e2e.env* 加进 .gitignore。在 e2e 分支里创建测试管理员
用 Node 自带的 --env-file 参数，让 DAY 46 的脚本读 .env.e2e：
node --env-file=.env.e2e --import tsx scripts/create-admin.ts脚本会先打印数据库主机名，确认是 e2e 分支的地址，管理员邮箱是 e2e-admin@example.com，然后输入 .env.e2e 里写的那个测试密码。脚本开头的 import "dotenv/config" 还会读 .env，但它不会覆盖已经由 --env-file 读进来的变量，所以连的仍是 e2e 分支。
安装 Playwright
npm init playwright@latest它会问几个问题，这样回答：语言选 TypeScript；测试文件夹填 e2e；是否添加 GitHub Actions 工作流选否（明天我们自己写）；是否安装浏览器选是。安装完会生成 playwright.config.ts 和一个示例测试，删掉示例：rm e2e/example.spec.ts（如果还生成了 tests-examples 文件夹，也一起删掉）。
替换配置文件，检查 .gitignore
用第 4 节的内容整个替换 playwright.config.ts。然后打开 .gitignore，确认安装程序已经加上了下面这些行，没有就补上：
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/在 package.json 的 scripts 里加一行："test:e2e": "playwright test"。配置文件用到了 dotenv，DAY 42 配 Prisma 时一般已经装过；如果运行时提示找不到它，执行 npm install -D dotenv。
写三条测试
在 e2e 文件夹里新建 helpers.ts、question.spec.ts、admin-login.spec.ts、publish-look.spec.ts，内容照第 5 到 7 节。第 5 节的选择器要对照你的提问箱页面改成实际文字。三条测试的步骤你自己写，写之前先在浏览器里手动走一遍这个流程，把每一步“点了什么、看到什么”记下来，再翻译成代码。
停掉开发服务器，运行测试
先在运行 npm run dev 的终端按 Ctrl + C 停掉它，然后：
npm run test:e2e第一次运行要等 Next.js 启动和编译，可能一两分钟。
用界面模式看它怎么点
npx playwright test --ui会打开一个窗口，左边是测试列表，点某条测试的运行按钮，右边能一步步看到浏览器里发生了什么，每一步都有截图。这是理解和调试测试最直观的方式。
故意让一条测试失败
把 look-form.tsx 里按钮的文字从“保存”改成“提交保存”，再运行 npm run test:e2e。第三条会失败，并自动打开 HTML 报告。在报告里点开失败的测试，看错误信息（找不到名为“保存”的按钮）、失败时的截图和 trace 操作记录。看懂后把按钮文字改回“保存”，再跑一次，全部通过。
这个练习说明了一件事：端到端测试会盯住用户看得到的文字。改界面文字时，要记得同步改测试。
提交
git status
git add -A
git commit -m "加入 Playwright：提问、登录、发布 look 三条端到端测试"提交前确认列表里没有 .env.e2e、test-results 和 playwright-report。
npm run dev 还开着。这正是 reuseExistingServer: false 在保护你，停掉它再跑测试。.env.e2e 里写的不一致。重新运行第 3 步，注意核对打印出的主机名。htmlFor 关联到输入框。用 npx playwright test --ui 看失败那一步的页面截图对照。revalidatePath。先手动在浏览器里重复一遍这个流程。.env.e2e 的 DATABASE_URL 是不是 e2e 分支的地址，配置文件开头有没有读取它，以及 Vercel 拉下来的 .env.local 里有没有 DATABASE_URL。单元测试和端到端测试各适合测什么？
单元测试适合测纯函数和规则：计分、日期格式、校验规则、图片格式判断。它不需要浏览器和数据库，几毫秒一个，出错时直接指出哪条规则坏了，可以写很多。端到端测试适合测完整的用户流程：粉丝提交提问、管理员登录、发布 look 后前台能看到。它打开真实浏览器、连真实数据库，能发现零件之间配合出的问题，比如按钮文字改了、忘了刷新缓存、权限拦错了；但它慢、出错时要再找原因，所以只写最关键的几条。
为什么端到端测试不能直接连你平时开发用的数据库？你是怎么隔开的？
端到端测试会真的写入和删除数据，连开发库会留下一堆测试垃圾，测试写错时还可能删掉真实内容。我用 Neon 从 production 分支复制了一个 e2e 分支，写在 .env.e2e 里；Playwright 配置开头读取这个文件，启动的网站就连 e2e 分支；测试管理员是只存在于 e2e 分支的 e2e-admin@example.com，通过 ADMIN_EMAIL 环境变量指定。另外 reuseExistingServer: false 防止测试误用我自己开着的、连开发库的服务器。
第三条测试里，look 的标题为什么要加上 Date.now()？最后为什么要删掉它？
加上时间戳让每次运行的标题都唯一，检查“前台能看到它”时，看到的一定是这一次新建的那条，而不是以前遗留的同名数据，否则就算这次保存失败，测试也可能误判为通过。最后删掉是为了让测试库保持干净，测试跑一百次也不会堆满一百条测试 look，同时顺带测试了删除流程。
.github/workflows/ci.yml，让每次推送到 main 和每个 Pull Request 自动跑类型检查、单元测试和构建。这两天你有了 15 个单元测试、3 个端到端测试，还有 TypeScript 的类型检查和 Next.js 的构建检查。它们都很有用，但有个前提：你得记得去跑。人总会忘，尤其是改了一行“肯定没问题”的小地方、急着推上去的时候。
CI（Continuous Integration，持续集成）的意思是：每次代码推到 GitHub，就由一台机器自动把检查全部跑一遍，结果标在这次提交旁边：绿色对勾是通过，红色叉是失败。你不用记得，机器替你记得。
打个比方：正式比赛上场前，裁判会检查拳套、护齿、绑手带，不管你是新人还是老将，每场都查，而且不是你自己查。CI 就是你代码的赛前检查，谁的代码、多小的改动，都照查不误。
以后你的网站上线了（明天），代码一合并就会自动部署。如果没有 CI，一个没跑过的改动可能直接把线上网站弄坏；有了 CI，坏的改动在合并前就被红叉拦住。
GitHub Actions 是 GitHub 自带的 CI 服务。你在仓库里放一个配置文件，GitHub 就会按照文件里写的，在它的服务器上开一台临时的 Linux 电脑，把你的代码拉下来，一步步执行命令，跑完就把这台电脑销毁。公开仓库免费，私有仓库每月也有一定的免费分钟数，个人项目通常够用。
配置文件放在 .github/workflows/ 文件夹里，用 YAML 格式写。YAML 是一种靠缩进表示层级的配置格式，缩进必须用空格（通常两个），不能用 Tab。结构有四层：
check。uses 表示使用别人写好的现成动作（比如“拉取代码”“安装 Node.js”），run 表示执行一条终端命令。一个步骤失败（命令返回错误），后面的步骤就不再执行，整个任务标红。
uses 后面写的现成动作，本质上是别人写的代码，会在跑你的 CI 时执行，而且能读到你传进去的密钥。所以只用可信来源的动作：今天用的 actions/checkout 和 actions/setup-node 都是 GitHub 官方维护的。以后在网上看到别人推荐的第三方动作，先看它是谁维护的、有多少人用，不确定就别用。这和“不从不明来源下载运行文件”是一个道理。
我们的 CI 跑三项检查，从快到慢排：
next typegen && tsc --noEmit。tsc 是 TypeScript 编译器，--noEmit 表示只检查、不生成文件。前面的 next typegen 先生成 Next.js 的路由类型，这是 Next.js 官方文档推荐的写法，否则 tsc 可能因为缺少这些类型文件报错。几十秒就能发现“把数字当字符串用”这类错误。vitest run，就是昨天的 npm test。next build，和 Vercel 部署时做的一样。本地能跑不代表能构建成功，比如某个页面在构建时查询数据库出错。快的放前面：类型错了就没必要再花几分钟构建，早失败早知道。
端到端测试这次先不放进 CI。它需要启动网站、安装浏览器、连测试数据库、准备测试账号，配置复杂，跑一次也慢。对现阶段的你来说，提交前在本地跑 npm run test:e2e 就够了。等你熟练了，可以参考 Playwright 文档把它加进来。
还有一个准备工作 DAY 42 已经替你做好了：CI 的临时电脑上没有 Prisma 生成的客户端代码（app/generated/prisma 不提交到 Git），所以 package.json 里有一个 postinstall 脚本，内容是 prisma generate。postinstall 是 npm 的约定：每次装完依赖会自动运行它。CI 执行 npm ci 时就会顺便生成 Prisma 客户端，明天部署到 Vercel 也靠它，这正是 Prisma 的 Vercel 部署文档推荐的写法。今天打开 package.json 确认它还在。
dongge-web/.github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
env:
DATABASE_URL: ${{ secrets.DATABASE_URL }}
BETTER_AUTH_SECRET: ${{ secrets.BETTER_AUTH_SECRET }}
BETTER_AUTH_URL: http://localhost:3000
steps:
- name: 取出代码
uses: actions/checkout@v6
- name: 安装 Node.js
uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- name: 安装依赖
run: npm ci
- name: 类型检查
run: npm run typecheck
- name: 单元测试
run: npm test
- name: 构建
run: npm run build逐段解释：
name: CI：工作流的名字，显示在 GitHub 的 Actions 页面。on：两种情况触发。推送到 main 分支时跑；有人向 main 开 Pull Request、或者往 PR 的分支继续推送时也跑。runs-on: ubuntu-latest：用最新的 Ubuntu Linux 临时电脑。env：给这个任务的所有步骤设置环境变量。${{ secrets.DATABASE_URL }} 表示从仓库的 Secrets 里读取，下一节讲。构建时 Next.js 可能会预先渲染读数据库的页面，Better Auth 在生产模式下也要求有密钥，所以这两个变量必须有。actions/checkout：把你的仓库代码拉到临时电脑上。actions/setup-node：安装 Node.js 24。cache: npm 会缓存下载过的依赖包，下次跑得更快。Node 大版本最好和你电脑上 node -v 的一致。npm ci：和 npm install 类似，但严格按照 package-lock.json 安装，保证 CI 装的版本和你本地完全一样。装完会自动触发 DAY 42 加的 postinstall，生成 Prisma 客户端。@v6、@v7 是这两个现成动作的大版本号，写这份课件时 GitHub 官方文档用的是这两个版本。官方以后升级了，照文档改成新的版本号即可，旧版本通常也还能用一段时间。配置文件会提交到 Git，所以里面绝不能直接写数据库地址和密钥。GitHub 提供了 Secrets：在仓库设置里填好，工作流里用 ${{ secrets.名字 }} 引用。它们加密保存，填好后连你自己都看不到明文，日志里如果出现也会被自动替换成 ***。
CI 用哪个数据库？绝不能是正式库。CI 会在每个 Pull Request 上运行，构建过程会连数据库；以后如果你把端到端测试也加进 CI，它还会往数据库里写东西。用昨天的 e2e 分支最合适：它是副本，弄乱了也能一键重置。
BETTER_AUTH_SECRET 也单独生成一个新的，不要复用本地或正式环境的。原则是：每个环境一把钥匙，一把丢了不影响其他。
Secrets 旁边还有一个 Variables（变量），用来放不敏感的配置，比如网站地址。区别是 Variables 的值能被看到，Secrets 看不到。像 BETTER_AUTH_URL 这种不是秘密的，我们直接写在 ci.yml 里就行。还有一点要知道：如果将来有陌生人复制（fork）了你的仓库再向你提 PR，那次 CI 是读不到你的 Secrets 的，这是 GitHub 为了防止密钥被别人的代码偷走而做的保护。
到今天为止，你都是直接在 main 分支上改、直接提交推送。明天网站上线后，main 分支就等于正式网站：推到 main 的代码会自动部署。直接往 main 上推没检查过的代码，就像直播时现场改稿，出错了所有人都看得到。
从今天起，改功能都走这个流程：
git switch -c feat/look-sort。分支名用前缀表示类型：feat/ 新功能，fix/ 修 bug，chore/ 杂项（比如配置），后面用英文短词说明内容。git push -u origin feat/look-sort。git switch main，git pull。两个让 PR 更好用的习惯：一是 PR 要小，一个 PR 只做一件事，比如“look 列表加排序”，不要把排序、改配色、修错别字混在一起，这样审查时一眼能看完，出了问题也容易回退；二是 PR 的说明写清三件事：改了什么、为什么改、你怎么验证的（比如“本地跑过 npm test 和 npm run test:e2e，手机上看过列表页”）。一个月后回头查某个改动时，你会感谢现在写了说明的自己。
这个流程看起来比直接推多了几步，但它给了你一个“合并前的检查站”：CI 帮你查，PR 页面让你以旁观者的眼光再看一遍自己的改动。等 DAY 55 以后，Claude 替你写的代码越来越多，这个检查站就更重要了：Claude 的改动也要走 PR，你审查通过才合并。
明天把网站接到 Vercel 正式上线后，每个 PR 还会自动得到一个“预览部署”：一个临时网址，能在合并前用手机打开看看效果。
CI 失败时，GitHub 会在 PR 页面底部显示红叉，并给你发邮件。找原因的路径是：
check，右侧会列出每一步。失败的那一步前面是红叉，点开它。如果是单元测试失败，你会看到和本地一样的 Vitest 输出，类似这样：
FAIL lib/quiz.test.ts > scoreQuiz 计分 > 三个世界各一票时，最后一题选的那个世界胜出
AssertionError: expected 'gentleman' to be 'thai'
- Expected: "thai"
+ Received: "gentleman"
at lib/quiz.test.ts:14:5
Test Files 1 failed | 2 passed (3)
Tests 1 failed | 14 passed (15)第一行告诉你哪个文件、哪一组、哪个测试失败；Expected 是测试期望的值，Received 是代码实际算出来的；lib/quiz.test.ts:14:5 是出错的文件、行号和列号；最后两行是汇总。这就是为什么测试名要用中文写清楚：你在日志里一眼就能看懂是哪条规则坏了。
如果是类型检查失败，日志里会有类似 app/admin/page.tsx(12,5): error TS2322 的行，括号里是行号和列号，后面是错误说明。构建失败则要看 Next.js 打印的报错，通常会指出是哪个页面。
找到原因后，在同一个分支上修改、提交、推送，CI 会自动重跑，PR 页面会更新结果。不需要关掉 PR 重开。
新建分支
今天的改动本身就走一遍 PR 流程：
cd ~/code/dongge-web
git switch main
git pull
git switch -c chore/ci加 npm 脚本，先在本地跑一遍
打开 package.json，确认 scripts 里有 DAY 42 加的 "postinstall": "prisma generate"，再加一行（已有的保持不变）：
"typecheck": "next typegen && tsc --noEmit"然后依次运行，三项都要在本地先通过：
npm run typecheck
npm test
npm run build在 GitHub 添加 Secrets
打开 GitHub 上的 dongge-web 仓库，点 Settings，左侧找到 Secrets and variables，点 Actions，点 New repository secret，添加两个：
DATABASE_URL：填 .env.e2e 里 e2e 分支的地址。不加引号，不要有多余空格。BETTER_AUTH_SECRET：用 openssl rand -base64 32 新生成一个。写 CI 配置
mkdir -p .github/workflows新建 .github/workflows/ci.yml，内容照第 4 节。YAML 靠缩进分层级，建议让 Claude 写好后，你对照第 4 节的解释逐行读，确认每一行在做什么，特别是缩进。
提交、推送、开 PR
git add -A
git commit -m "加入 CI：类型检查、单元测试、构建"
git push -u origin chore/ci推送后终端会打印一个创建 Pull Request 的链接，点开它，标题写“加入 CI”，说明里写一句这次改了什么，点 Create pull request。如果你装了 GitHub 命令行工具 gh，也可以直接运行 gh pr create --fill。
看 CI 跑起来
PR 页面底部会出现 CI 的检查项，状态是黄色的“运行中”。点 Details 可以实时看每一步的输出。等几分钟。
合并，回到 main
在 PR 页面点 Squash and merge，确认，然后点 Delete branch。回到终端：
git switch main
git pull
git branch -d chore/ci打开仓库的 Actions 标签页，合并到 main 这一下又触发了一次 CI，也应该是绿的。
故意让测试失败
新开一个练习分支，把一个测试的期望值改错：
git switch -c test/break-ci打开 lib/quiz.test.ts，把“三个世界各一票时”那条的期望值 "thai" 改成 "gentleman"。提交、推送、开 PR。
修好它，看 CI 变绿，然后关掉练习 PR
把期望值改回 "thai"，在同一个分支提交、推送。PR 页面的 CI 会自动重跑并变绿。这是一个练习，不需要合并：在 PR 页面点 Close pull request，再删掉分支：
git switch main
git branch -D test/break-ci
git push origin --delete test/break-ci（可选）要求 CI 通过才能合并
在仓库 Settings 里找到 Rules 下的 Rulesets（或 Branches），给 main 加一条规则：合并前必须通过 CI 检查。GitHub 免费账号对公开仓库提供这个功能，私有仓库可能需要付费计划；用不了也没关系，给自己定一条规矩：永远不直接推 main，永远等绿了再合并。
DATABASE_URL。检查 GitHub Secrets 里有没有这个名字，拼写和大小写要完全一致，值是 e2e 分支的地址且没有多余的引号或空格，以及 ci.yml 的 env 缩进是否在 check 下面。next typegen 在本地生成过类型文件而 CI 上没有。用 git status 确认所有文件都提交了，脚本里保留 next typegen && 这一段。BETTER_AUTH_SECRET，或者 ci.yml 里没把它放进 env。git switch main 再 git pull，就直接在旧的 main 上改了。先 git pull 把远程的改动拉下来再推。故意让一个测试失败，读懂 CI 日志里的报错。
路径：PR 页面点红叉旁的 Details（或 Actions 页面点这次运行），左侧点 check 任务，展开标红的“单元测试”步骤。日志里 FAIL 那一行写着失败的文件和测试名，例如“lib/quiz.test.ts，scoreQuiz 计分，三个世界各一票时，最后一题选的那个世界胜出”；Expected 是测试期望的值，Received 是代码实际返回的值；带行号的那一行指出出错的位置；末尾汇总几个失败、几个通过。能说出“哪条规则、期望什么、实际是什么、错在测试还是代码”就算读懂了。本题中是测试的期望值被改错了，代码本身没问题。
为什么 CI 里的 DATABASE_URL 不能用正式库？
CI 会在每个 Pull Request 上运行，包括还没审查、可能有问题的代码；构建时会连数据库，以后加入端到端测试还会往库里写数据。连正式库就等于让没检查过的代码碰真实数据，还可能留下测试垃圾。用 e2e 分支这种副本，弄乱了也能重置，不影响粉丝看到的内容。另外每个环境用各自的密钥，一处泄露不会波及其他环境。
为什么要走 Pull Request，而不是直接推到 main？
上线后 main 就是正式网站，推上去会自动部署。PR 给了合并前的检查站：CI 自动跑类型检查、测试、构建，红了就不合并；PR 页面把所有改动集中展示，方便自己或 Claude 审查；Vercel 还会给 PR 生成预览网址，能先在手机上看效果。直接推 main 就跳过了这些检查，出错会直接影响线上。
/code-review 审查全项目，按优先级修完高优先级问题，其余的记成待办。prisma migrate dev 和 prisma migrate deploy 的区别，并让 Vercel 在每次构建时自动执行 migrate deploy。从 DAY 38 新建 dongge-web 到今天，你写了前台、数据库、提问箱、登录、后台、图片上传、审核、测试、CI。今天是阶段 4 的作品日，要把它变成一个真正在线、你每天都会用的网站。上线之前，先做一次全面体检。
DAY 35 你用过 Claude Code 的 /code-review 审查组件。今天范围更大，按文件夹分批审查，每次只看一块，意见更集中：
/code-review app/admin
/code-review lib
/code-review app/api
/code-review proxy.ts审查意见会很多，不可能全改。按严重程度分三档处理：
| 优先级 | 例子 | 怎么处理 |
|---|---|---|
| 高 | 某个后台页面或 Server Action 漏了 requireAdmin()；密钥写进了代码；用户输入没校验就进了数据库；可能删错数据 | 今天必须修完才上线 |
| 中 | 某种边界情况会报错页，比如编辑一条已被删除的 look | 记成 GitHub issue，DAY 70 全面审查时处理 |
| 低 | 命名不统一、可以抽成组件、样式写法 | 记下来，有空再说 |
这一阶段 Claude 是你的结对搭档，不是替你拍板的人。每条意见你都要读懂，自己判断“它说得对不对、值不值得现在改”。高优先级的安全问题，修的时候你亲手改，改完再让 Claude 复查一次。
体检时特别对照这份安全清单，逐条确认：
app/admin 下每个 page.tsx 第一行都调用了 requireAdmin()。"use server" 文件里导出的函数，第一行都调用了 requireAdmin()（提问箱的“粉丝提交”除外，它本来就是公开的，但有 Zod 校验）。git log -p 里也搜不到 BETTER_AUTH_SECRET= 这样的字样。一个像样的网站通常同时存在三个“环境”，每个环境是网站的一份独立运行的副本：
| 环境 | 在哪里 | 谁在用 | 连哪个数据库 |
|---|---|---|---|
| 开发（Development） | 你的 Mac，npm run dev | 你写代码时 | Neon 的 development 分支 |
| 预览（Preview） | Vercel，每个 PR 一个临时网址 | 你合并前检查效果 | 也用 development 分支 |
| 正式（Production） | Vercel，正式网址 | 粉丝 | Neon 的 production 分支 |
打个比方：开发是你在家对着镜子试衣服，预览是出门前让朋友帮你看一眼，正式是走上街。在家怎么折腾都行，上街的那一身要确认没问题。
为什么要分开？因为你在开发时会做很多“破坏性”的事：造测试数据、改表结构、删东西重来。如果开发和正式共用一个数据库，你在家试衣服时，粉丝就在街上看着你换。分开之后，你本地怎么折腾都不会影响粉丝看到的网站。
每个环境有自己的一套环境变量：自己的数据库地址、自己的 BETTER_AUTH_SECRET。本地的放在 .env 和 .env.local，Vercel 上的在项目设置里按环境分别填写。
回顾一下现状：DAY 40 你在 Neon 控制台建项目时，Neon 自动创建的根分支叫 production。之后你一直在这个分支上开发，DAY 46 创建的管理员账号、DAY 48 以来建的 look、DAY 50 审核过的提问，都在这里。DAY 52 你又从它复制出了一个 e2e 分支给测试用。
今天的做法最简单：让 production 分支名副其实，成为正式库；再从它复制出一个 development 分支，你本地以后连这个。也就是说，不用搬数据，只是“换个地方开发”：
.env，让 DATABASE_URL 指向它。以后本地造的测试数据只进这里。如果你的根分支叫 main（通过命令行创建的项目会这样），把下文所有的 production 分支换成 main 分支。
.env。本地 .env 只放 development 分支的地址。这样你在本地运行任何命令，都碰不到正式数据。DAY 42 以来，你每次改 schema.prisma 都运行 npx prisma migrate dev。它做了两件事：对比 schema 和数据库的差异，生成一个新的迁移文件放进 prisma/migrations；然后把它应用到数据库。如果它发现数据库和迁移记录对不上，还会提示你重置数据库，也就是清空所有数据重来。这对开发库无所谓，对正式库就是灾难。
npx prisma migrate deploy 是给正式环境用的：它只应用还没应用过的迁移文件，从不生成新迁移，从不重置数据库。数据库里有一张 _prisma_migrations 表，记录着哪些迁移已经执行过，migrate deploy 就是对照这张表，把缺的补上。没有缺的，它就打印“没有待应用的迁移”，什么也不做。
| migrate dev | migrate deploy | |
|---|---|---|
| 生成新迁移文件 | 会 | 不会 |
| 应用迁移 | 会 | 会，只应用还没应用的 |
| 可能重置数据库 | 可能 | 永远不会 |
| 用在哪 | 本地开发库 | 正式库（以及预览、测试库） |
所以以后改数据库结构的完整流程是：本地改 schema，运行 migrate dev，在 development 分支上试好；把 prisma/migrations 里新生成的文件和代码一起提交；走 PR，CI 变绿后合并；Vercel 构建时自动运行 migrate deploy，把这个新迁移应用到正式库。迁移文件夹一定要提交进 Git，它就是正式库“该长什么样”的说明书。
谁来对正式库运行 migrate deploy？Prisma 的部署文档建议把它放进自动化的部署流程里，而不是在自己电脑上手动对正式库运行，因为手动操作容易连错库、忘了跑。Prisma 的 Vercel 部署文档给了现成的写法：在 package.json 里加一个构建脚本。
"postinstall": "prisma generate",
"vercel-build": "prisma generate && prisma migrate deploy && next build"postinstall 是 DAY 42 就加好的，CI 和 Vercel 装完依赖都会自动运行它。vercel-build 依次做三件事：生成 Prisma 客户端，对当前环境的数据库应用迁移，构建网站。三者用 && 连起来，前一步失败后一步就不执行：迁移失败，就不会上线一个和数据库对不上的新版本，线上继续运行旧版本。
Next.js 项目在 Vercel 上默认运行的是 build 脚本，所以要到项目设置里把 Build Command 改成 npm run vercel-build。为什么不直接把迁移写进 build？因为 CI 和你本地也会运行 npm run build，我们不希望它们去改数据库结构。分成两个脚本，职责清楚。
还有一个 Neon 的细节。Neon 的连接地址有两种：主机名里带 -pooler 的是“连接池”地址，适合大量短连接；不带的是“直连”地址。Neon 的文档建议迁移这类命令行操作用直连地址。DAY 42 你复制连接地址时关掉了 Connection pooling 开关，用的就是直连地址，所以今天照旧：Vercel 上的 DATABASE_URL 填 production 分支的直连地址，运行网站和迁移都用它。对个人网站的访问量，直连完全够用；等以后访问量大了，再按 Neon 文档拆成“运行用连接池、迁移用直连”两个地址。
在 Vercel 项目的 Settings 里找到 Environment Variables，每个变量可以勾选它属于哪几个环境。dongge-web 需要这些：
| 变量 | Production | Preview | 说明 |
|---|---|---|---|
| DATABASE_URL | production 分支的直连地址 | development 分支的地址 | 预览环境绝不能连正式库 |
| BETTER_AUTH_SECRET | 新生成一个 | 再新生成一个 | 每个环境一把钥匙 |
| BETTER_AUTH_URL | 正式网址，如 https://dongge-web.vercel.app | 不填 | 要带 https，结尾不要斜杠 |
| ADMIN_EMAIL | 你的邮箱 | 你的邮箱 | 决定谁是管理员 |
| BLOB_READ_WRITE_TOKEN 等 | 已自动添加 | 已自动添加 | DAY 49 连接 Blob 存储时 Vercel 加的 |
Development 这一列不需要你手动填数据库地址。它只在你运行 vercel env pull 时有用，里面只放 Blob 相关的变量就好；本地的数据库地址由你自己的 .env 管。
预览环境的 BETTER_AUTH_URL 不填，因为每个 PR 的预览网址都不一样。预览环境主要用来在合并前看页面效果；后台登录以正式网址为准。
改了环境变量，已经部署的版本不会自动生效，要重新部署一次才会读到新值。
上线后，你在手机上打开后台，新建一条 look，点“保存”。这一下背后发生了这些事，今晚的验收题就是把它讲出来：
multipart/form-data，连同会话 Cookie 和 Server Action 的编号，作为一个 POST 请求发给 Vercel。proxy.ts，它看到有会话 Cookie，放行。createLook，在 Vercel 的服务端函数里运行它。requireAdmin() 用 Cookie 里的令牌去 Neon 的 session 表查，找到用户，再比对邮箱是否等于 ADMIN_EMAIL。不是就跳去登录页，后面都不执行。lookSchema 去掉空格、检查长度、把世界 id 转成数字。不通过就把错误和你填的内容返回给表单。checkImage 检查大小和文件头，确认是真图片；put 把它上传到 Vercel Blob，拿回一个公开网址。prisma.look.create 生成一条 SQL 的 INSERT 语句，在 Neon 的 production 分支里的 Look 表新增一行，imageUrl 存的是刚才的网址。revalidatePath("/", "layout") 告诉 Next.js 全站页面的缓存都过期了。redirect 让浏览器回到后台列表，列表重新查询，新 look 出现在第一行。prisma.look.findMany，只取已发布的 look，生成新的 HTML；照片由 next/image 从 Blob 网址取来，压缩成适合手机的尺寸。粉丝看到了你刚发的 look。整个过程你没有改一行代码、没有重新部署。这就是做后台的意义：以后更新内容不用再改代码。代码只在你想加新功能时才动，而且要走 PR、过 CI。
新建分支，全项目审查
cd ~/code/dongge-web
git switch main
git pull
git switch -c chore/launch在 Claude Code 里按第 1 节分批运行 /code-review。把意见按高、中、低分好。高优先级的逐条修，每修一条单独提交一次，提交信息写清修了什么。中低优先级的在 GitHub 仓库的 Issues 里各建一条，标题写清问题，留到 DAY 70。
npm run typecheck、npm test、npm run test:e2e 全部通过。在 Neon 建 development 分支，切换本地连接
Neon 控制台，Branches，New branch：父分支选 production，名字填 development，包含当前数据，创建。点 Connect，切到 development 分支，数据库选 neondb，关掉 Connection pooling，复制地址。
打开本地 .env，把 DATABASE_URL 换成 development 分支的地址（如果你还有直连地址的变量，也一起换）。然后重启 npm run dev，登录后台看看。
加 vercel-build 脚本
打开 package.json，在 scripts 里加上第 5 节的 vercel-build（postinstall DAY 42 就有了）。提交：
git add -A
git commit -m "加入 vercel-build：构建时运行 prisma migrate deploy"配环境变量
Settings，Environment Variables，按第 6 节的表逐个添加。每个变量添加时注意勾选的环境：
DATABASE_URL 添加两次：一次只勾 Production，值是 production 分支的直连地址；一次只勾 Preview，值是 development 分支的地址。BETTER_AUTH_SECRET 同样分两次添加，每次都用 openssl rand -base64 32 新生成。BETTER_AUTH_URL 只勾 Production。正式网址在项目 Overview 页面的 Domains 里能看到。ADMIN_EMAIL 勾 Production 和 Preview。改构建命令
Settings，Build and Deployment，在 Framework Settings 里找到 Build Command，打开 Override 开关，填 npm run vercel-build，保存。
把 Vercel 项目连上 GitHub 仓库
打开 Vercel 上的 dongge-web 项目，Settings，找到 Git。DAY 49 你用 vercel link 新建项目时没有连 Git，现在点连接，选择你的 dongge-web 仓库，生产分支用 main。环境变量和构建命令在前两步已经配好，所以现在连才合适。这是 dongge-web 第一次部署：DAY 38 说过，它要等到今天连同数据库一起上线。连接后 Vercel 可能会立刻对 main 部署一次。main 上还没有 vercel-build 脚本（它在你的 chore/launch 分支上），所以这次部署会失败，属于正常；等你合并 PR 后，Vercel 会自动再部署，那次才是真正的上线。
推送、开 PR、看预览构建
git push -u origin chore/launch开 PR。等两样东西：GitHub 的 CI 检查，以及 Vercel 自动创建的预览部署（PR 页面会出现 Vercel 的评论或检查项）。点进 Vercel 的预览部署，打开 Building 日志，找 prisma migrate deploy 那一段。
合并，正式上线
在 PR 页面点 Squash and merge。合并到 main 会触发正式部署。在 Vercel 项目的 Deployments 页面看最新一条 Production 部署，打开构建日志找到迁移那一段。
线上后台：登录并清理测试数据
打开 正式网址/admin，被带到登录页，用你的管理员账号登录（它本来就在 production 分支里）。然后：
上线验收：用手机发一条真的 look
拿出手机，打开正式网址的后台，登录，新建一条真实的 look：比如“泰拳训练日：黑色泰拳短裤”，描述写具体搭配，从相册选一张照片，勾选发布，保存。然后用手机打开前台首页。
再用手机以访客身份在提问箱提一个问题，回到后台通过它、写上回答，确认前台能看到。
记下上线信息，学会回滚
在你的笔记里记下：正式网址、后台地址、三个 Neon 分支各给谁用、Vercel 环境变量在哪里改。然后打开 Vercel 的 Deployments 页面看一眼：每次部署都保留着，如果哪天新版本出了问题，可以在上一个正常的 Production 部署右侧菜单里选 Instant Rollback，几秒钟退回旧版本，再慢慢修。
最后给这个里程碑打个标签：
git switch main
git pull
git tag v1.0-admin
git push origin v1.0-adminDATABASE_URL。改完要点 Redeploy 重新部署。-pooler 的连接池地址来迁移。把 Production 的 DATABASE_URL 换成直连地址（Neon 的 Connect 弹窗里关掉 Connection pooling 再复制），重新部署。BETTER_AUTH_URL 和你浏览器地址栏里的网址不一致。常见原因是填成了预览网址、少了 https、结尾多了斜杠。DAY 69 绑定自己的域名后，也要记得把它改成新域名。ADMIN_EMAIL，或者和你的登录邮箱不一致。requireAdmin() 在没配置时默认拒绝所有人，这是设计好的保护。不看代码，讲一遍：在后台新增一条 look，从点“保存”到前台出现，经历了什么。
浏览器把表单字段和照片打包成 multipart/form-data，带着会话 Cookie 和 Server Action 编号，向 Vercel 发 POST 请求。proxy.ts 看到有会话 Cookie，先放行。Next.js 按编号找到 createLook 并在服务端运行。requireAdmin 拿 Cookie 里的令牌查 Neon 的 session 表，确认登录且邮箱等于 ADMIN_EMAIL，否则跳登录页。Zod 的 lookSchema 清洗并校验标题、描述、世界、发布状态，不通过就把错误返回表单。照片经过 checkImage 检查大小和文件头后，用 put 上传到 Vercel Blob，得到公开网址。Prisma 生成 INSERT，把这条 look 连同图片网址写进 Neon production 分支的 Look 表。revalidatePath 让全站缓存失效，redirect 把我带回后台列表。粉丝打开首页时，服务端组件重新查询已发布的 look，生成新页面，next/image 从 Blob 取图并压缩，新 look 就出现了。全程没有改代码、没有重新部署。
prisma migrate dev 和 prisma migrate deploy 有什么区别？为什么正式库只能用后者？
migrate dev 会根据 schema 的变化生成新的迁移文件并应用，发现数据库和迁移记录对不上时还可能提示重置数据库、清空数据，只适合开发库。migrate deploy 只对照 _prisma_migrations 表，把已提交但还没应用的迁移补上，从不生成新迁移、从不重置。正式库里是粉丝和你的真实内容，不能冒被清空的风险，所以只用 migrate deploy，并且放进 Vercel 的构建命令里自动执行，避免手动连错库。
为什么正式环境的 BETTER_AUTH_SECRET 要和本地、预览、CI 的都不一样？
这个密钥用来给登录令牌签名。每个环境一把钥匙，其中一把泄露（比如本地的 .env 不小心被别人看到），攻击者也拿它伪造不了正式网站的登录状态。同理，正式库地址只放在 Vercel 的 Production 环境里，本地、预览、CI 都连不到它，任何一处出问题都波及不到粉丝看到的网站。
usage 估算一次调用大约花多少钱。.env，并确认它不会进 Git、不会进浏览器。@anthropic-ai/sdk 写出一个只有管理员能调用的接口 /api/ai/ask：输入一句话，返回 Claude 的回答。stop_reason（包括 refusal），并说清服务端兜底 fallbacks 帮你做了什么。到 DAY 54 为止，dongge-web 已经有前台、后台、测试和自动化检查。从今天起九天，你要给后台加上 AI：先打通最小接口，再做文案助手和数据看板，最后合成「东哥内容工作台」。
先用一个比喻。你平时在 Claude Code 里聊天，像是走进一家餐厅，坐下点菜，服务员会记住你刚才说过什么。API 不一样，它像是后厨的“出餐窗口”：你每次递进去一张写得清清楚楚的工单，后厨照单做好递出来，然后就把这张单子忘了。API 是 Application Programming Interface（应用程序接口）的缩写，意思是“让程序和程序对话的约定”。你的网站就是那个递工单的程序。
一张工单（一次请求）里最重要的几项是：
claude-opus-5。模型会更新，想换的时候去 Claude 文档的模型列表里挑一个新的 ID，改一处常量即可。user（你）还是 assistant（Claude）说的。后厨递回来的“餐盘”（响应）里，除了回答内容，还有两样你以后每天都要看的东西：stop_reason（为什么停下）和 usage（用了多少 token）。下面先把 token 讲清楚。
模型不是一个字一个字地读，而是把文字切成一小块一小块，每一块叫一个 token。英文里一个常见单词大约是一到两个 token，中文大致是一个汉字对应一个 token 左右。这只是粗略估计，准确数字以每次响应里的 usage 为准。
为什么要关心 token？因为三件事都按它算：
claude-opus-5 是每百万输入 token 5 美元、每百万输出 token 25 美元，价格会调整，以官方价格页为准。max_tokens 限制的是输出 token 数。max_tokens，也按输出计费。所以 max_tokens 不能设得太小，否则可能想完就没空间写答案了。我们统一设成 16000，这是上限不是消耗，没用到的部分不收钱。举个例子：你问一句话，系统提示词加问题一共 500 个输入 token，Claude 连思考带回答用了 1500 个输出 token。费用约为 500 × 5 ÷ 1000000 + 1500 × 25 ÷ 1000000 = 0.0025 + 0.0375 = 0.04 美元。单次很便宜，但一个写错的循环一晚上能调用几万次，所以下一节要先装“保险丝”。
上下文（context）是 Claude 这一次能看到的全部内容：系统提示词加上 messages 里的所有对话。Opus 5 的上下文很大（本地文档写的是 100 万 token），但每多带一句历史，就多付一次输入费。
API 是无状态的：它不会替你记住上一轮聊了什么。想要多轮对话，你得每次把完整历史重新发一遍，像这样：
messages: [
{ role: "user", content: "帮我想一个街头世界的视频主题" },
{ role: "assistant", content: "雨后空场地练 BMX，第三次落地摔了。" },
{ role: "user", content: "换成泰风世界" },
]逐行看：第一条是你说的话；第二条是 Claude 上一轮的回答，由你的程序存下来再原样发回去；第三条是你的新问题。规则有两条：第一条必须是 user；最后一条通常也是 user，表示“轮到 Claude 说了”。明天做对话页时，前端就是这样攒历史的。
系统提示词和 messages 的区别是：系统提示词是整场对话都有效的背景和规矩，放在 system 字段；messages 是具体这一轮说了什么。人设、写作分寸这类长期规则放 system，“今天要写斯诺克主题”这类一次性内容放 messages。DAY 57 会专门练怎么写系统提示词。
API Key 是一串以 sk-ant- 开头的密钥，谁拿到它，谁就能用你的账户调用 Claude，账单记在你头上。它和银行卡密码一样重要。三条规矩：
.env：DAY 45 学过，.env 在 .gitignore 里，不会被提交。变量名统一叫 ANTHROPIC_API_KEY。process.env.ANTHROPIC_API_KEY。Next.js 只会把 NEXT_PUBLIC_ 开头的变量打包进浏览器代码，其他变量在浏览器里会变成空字符串。所以千万不要给它起名 NEXT_PUBLIC_ANTHROPIC_API_KEY，那等于把钥匙贴在门上。为了让“只在服务端”由机器帮你把关，我们继续用 DAY 47 在 lib/admin.ts 里用过的 server-only 包（Next.js 文档推荐的做法）：在服务端文件第一行写 import "server-only";，以后如果有人不小心在 "use client" 组件里引入这个文件，构建时就会直接报错。
然后是保险丝：在 Claude Console 设每月用量上限。路径是 Settings 里的 Billing 页面，在 Spend limits 一栏点 Set limit（已有上限时叫 Adjust limit），填一个你能接受的金额。达到上限后，请求会返回 400 错误并提示已达到你设置的用量上限，不会继续扣钱。设多少、充值多少由你自己决定；自用的后台工具，先设一个小数目，看一周实际花费再调整是比较稳的做法。
.env，不要存在备忘录、截图或聊天记录里。万一泄露，马上在 Console 里把它删除（撤销），再建一个新的。SDK（Software Development Kit，软件开发工具包）是官方写好的一套代码，帮你把“拼请求、发网络、解析响应、出错重试”这些杂活包起来。我们用 @anthropic-ai/sdk。先看项目里统一创建客户端的文件：
dongge-web/lib/ai/claude.ts
import "server-only";
import Anthropic from "@anthropic-ai/sdk";
// 模型 ID。想换模型：去 Claude 文档的模型列表里挑一个，改这一行。
export const MODEL = "claude-opus-5";
// 服务端兜底 fallbacks 需要带上的测试版标记（第 6 节讲）。
export const FALLBACK_BETA = "server-side-fallback-2026-07-01";
let client: Anthropic | null = null;
export function getClaude() {
if (!client) {
const apiKey = process.env.ANTHROPIC_API_KEY;
if (!apiKey) {
throw new Error("缺少 ANTHROPIC_API_KEY：本地写进 .env，线上写进 Vercel 环境变量");
}
client = new Anthropic({ apiKey });
}
return client;
}逐行解释：
MODEL：全项目只在这里写模型名，别处都引用这个常量。以后换模型只改一处。let client 和 getClaude()：第一次调用时才创建客户端，之后复用同一个。为什么不在文件顶部直接 new？因为 next build 和 GitHub Actions 的 CI 里没有这个 Key，文件一被加载就报错会让构建失败；放进函数里，只有真正调用 AI 时才读取 Key。process.env.ANTHROPIC_API_KEY：在服务端读取环境变量。其实 new Anthropic() 不传参数也会自动读这个变量，我们显式写出来，是为了让你一眼看到 Key 从哪来，并在缺失时给出中文提示。一次请求返回的 JSON 大致长这样（省略了部分字段）：
{
"type": "message",
"role": "assistant",
"model": "claude-opus-5",
"content": [
{ "type": "thinking", "thinking": "", "signature": "..." },
{ "type": "text", "text": "我是 Claude，可以帮你写文案和整理想法。" }
],
"stop_reason": "end_turn",
"usage": { "input_tokens": 32, "output_tokens": 210 }
}注意 content 是一个数组，里面可能有好几种“块”：thinking（思考块，默认不返回原文，所以是空的）、text（真正的回答）等。所以不能想当然地读 content[0].text，第一块很可能不是文字。
stop_reason 告诉你它为什么停下，常见的值：end_turn 正常说完；max_tokens 写到上限被截断了，内容不完整；refusal 安全机制拒绝了这个请求，这时 content 可能是空的，也可能只有半截。Opus 5 带有安全分类器，偶尔会把正常请求误判，所以永远先看 stop_reason，再读 content。我们把这个检查写成一个纯函数：
dongge-web/lib/ai/reply.ts
import type Anthropic from "@anthropic-ai/sdk";
export type Reply =
| { ok: true; text: string; truncated: boolean }
| { ok: false; message: string };
export function readReply(message: Anthropic.Beta.BetaMessage): Reply {
// 1. 先看 stop_reason：被拒绝时不读内容
if (message.stop_reason === "refusal") {
return { ok: false, message: "这次请求被安全机制拒绝了，备用模型也没有接住。换个说法再试。" };
}
// 2. 只拼接 text 块，跳过 thinking、fallback 等其他块
let text = "";
for (const block of message.content) {
if (block.type === "text") {
text += block.text;
}
}
if (!text) {
return { ok: false, message: "Claude 没有返回文字，请重试。" };
}
// 3. max_tokens 表示写到上限被截断了
return { ok: true, text, truncated: message.stop_reason === "max_tokens" };
}Reply 是 DAY 26 学过的联合类型：要么成功带着文字，要么失败带着提示语。调用它的地方必须先判断 ok，TypeScript 才允许你读 text，这样就不会忘记处理失败。block.type === "text" 这一判断让 TypeScript 知道这个块有 text 字段。因为它是纯函数（不联网、不读数据库），很容易单独测试，也方便别的接口复用。
用大白话说：fallbacks 就是“备用厨师”。你在工单上注明“如果主厨因为安全规则不接这单，请直接交给备用厨师做”，这个换人的动作发生在 Anthropic 的服务器上，还在同一次请求里完成，你的代码不用写重试逻辑。它只在安全策略拒绝时触发；限流、服务器过载这类错误不会换人，照常返回错误给你。
按本地文档，给 claude-opus-5 开启它只需要三处改动：用 client.beta.messages（beta 表示“测试版功能”），带上测试版标记 server-side-fallback-2026-07-01，再加一个参数 fallbacks: "default"，让官方按拒绝的类别自动挑选推荐的备用模型。接口的核心代码如下：
dongge-web/app/api/ai/ask/route.ts
import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { getAdminSession } from "@/lib/admin";
import { getClaude, MODEL, FALLBACK_BETA } from "@/lib/ai/claude";
import { readReply } from "@/lib/ai/reply";
const AskInput = z.object({
question: z.string().trim().min(1, "说点什么吧").max(500, "最多 500 字"),
});
export async function POST(request: Request) {
// 1. 先确认是管理员
const session = await getAdminSession();
if (!session) {
return Response.json({ error: "请先登录后台" }, { status: 401 });
}
// 2. 再校验输入
const parsed = AskInput.safeParse(await request.json().catch(() => null));
if (!parsed.success) {
return Response.json({ error: parsed.error.issues[0].message }, { status: 400 });
}
try {
// 3. 调用 Claude：beta 接口 + 服务端兜底
const message = await getClaude().beta.messages.create({
model: MODEL,
max_tokens: 16000,
betas: [FALLBACK_BETA],
fallbacks: "default",
system: "你是东哥的写作助手。回答用简体中文，简短直接。",
messages: [{ role: "user", content: parsed.data.question }],
});
// 4. 先看 stop_reason 再读内容
const reply = readReply(message);
if (!reply.ok) {
return Response.json({ error: reply.message }, { status: 422 });
}
return Response.json({
answer: reply.text,
truncated: reply.truncated,
servedBy: message.model,
usage: { input: message.usage.input_tokens, output: message.usage.output_tokens },
});
} catch (error) {
if (error instanceof Anthropic.APIError) {
console.error("Claude API 出错", error.status, error.message);
return Response.json({ error: "AI 服务暂时不可用，稍后再试" }, { status: 502 });
}
throw error;
}
}逐段解释：
/api/ai/ask 发请求（DAY 47 讲过“绕过页面直接调用”），所以接口自己必须检查登录；Zod 校验挡住空内容和超长内容，避免浪费 token。getAdminSession() 来自 DAY 47 你自己写的 lib/admin.ts：它读取当前会话，并核对邮箱是不是 ADMIN_EMAIL，不是东哥就返回 null。这里没有用同一个文件里的 requireAdmin()，因为它在未登录时会跳转到登录页，那是给页面用的；接口的调用方是 fetch，应该收到一个 401 的 JSON，而不是一个跳转。temperature、top_p 这些“采样参数”。本地文档写明新模型不接受它们，传了会报 400，所以一律不写。message.model 是真正完成回答的模型。如果发生了兜底，这里会是备用模型的名字，我们把它作为 servedBy 返回，方便你观察。catch：只处理 SDK 的 APIError（Key 错误、限流、服务不可用等），把细节打印到服务器日志，给前端一句不泄露内部信息的话；其他意外错误继续抛出。lib/admin.ts 是 DAY 47 你亲手写的核心安全代码，今天只引用、不修改。审查 Claude 的实现时，如果看到它“新建”或“改写”了这个文件，要让它撤回。最后是后台页面。页面本身是服务端组件，只负责摆放；输入框要响应点击和输入，所以放进一个客户端组件，通过 fetch 调用刚才的接口。注意它完全不知道 Key 的存在。
dongge-web/app/admin/ai/ask-box.tsx
"use client";
import { useState } from "react";
export default function AskBox() {
const [question, setQuestion] = useState("");
const [answer, setAnswer] = useState("");
const [error, setError] = useState("");
const [loading, setLoading] = useState(false);
async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
event.preventDefault();
setLoading(true);
setError("");
setAnswer("");
try {
const res = await fetch("/api/ai/ask", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ question }),
});
const data = await res.json();
if (!res.ok) {
setError(data.error ?? "出错了");
} else {
setAnswer(data.answer);
}
} catch {
setError("网络出错了，请检查连接");
} finally {
setLoading(false);
}
}
return (
<form onSubmit={handleSubmit} className="space-y-3">
<textarea
value={question}
onChange={(e) => setQuestion(e.target.value)}
maxLength={500}
rows={3}
className="w-full rounded border p-2"
placeholder="问 Claude 一句话"
/>
<button disabled={loading} className="rounded bg-black px-4 py-2 text-white disabled:opacity-50">
{loading ? "思考中……" : "提问"}
</button>
{error && <p className="text-red-600">{error}</p>}
{answer && <p className="whitespace-pre-line rounded bg-gray-50 p-3">{answer}</p>}
</form>
);
}dongge-web/app/admin/ai/page.tsx
import { requireAdmin } from "@/lib/admin";
import AskBox from "./ask-box";
export default async function AiPage() {
await requireAdmin();
return (
<div className="mx-auto max-w-2xl space-y-4 p-6">
<h1 className="text-2xl font-bold">问 Claude</h1>
<AskBox />
</div>
);
}这个组件的写法你在 DAY 30 的留言表单里都见过：受控输入框、preventDefault、try/catch/finally。唯一的新东西是它请求的是自己网站的接口，真正联系 Claude 的是服务端。页面第一行照 DAY 47 的约定调用 requireAdmin()，未登录就跳到登录页；即使有人绕过页面直接调接口，接口自己的检查也会返回 401。
前面 54 天，代码主要是你敲、Claude 帮。从今天起换位置：你写需求，Claude 实现，你审查合并。这像你拍视频时当导演：你不用亲自扛机器，但你必须说清楚要拍什么、拍成什么样算过关，还要在回放时一眼看出哪条不能用。
一张好用的需求卡包含六块：
审查 Claude 的实现时，按这个顺序看：先看改了哪些文件（git status、git diff --stat），有没有动到需求以外的文件；再逐个文件读 diff，对照上午的参考代码，每一段都要能说出它在干什么，说不出来就让 Claude 解释；然后跑检查（类型检查、测试、构建）；最后亲手按验收标准点一遍。四步都过了，才开 Pull Request 合并。
MODEL 常量、是否用了 client.beta.messages 加 fallbacks、读内容前有没有检查 stop_reason。明天我们把接口升级成流式输出。在 Claude Console 设好用量上限
浏览器打开 Claude Console，登录后进入 Settings，找到 Billing 页面。是否充值、充多少由你自己决定。在 Spend limits 一栏点 Set limit，填一个每月上限。
创建两把 API Key，本地一把、线上一把
在 Console 的 API Keys 页面创建 Key，名字写 dongge-web-local。复制后立刻打开 VS Code，在 ~/code/dongge-web/.env 末尾加一行（等号两边不要有空格）：
dongge-web/.env
ANTHROPIC_API_KEY=sk-ant-这里粘贴你的本地Key再建一把 dongge-web-prod，先不要关页面，第 10 步要用。分开两把的好处是：哪一把泄露就只撤销哪一把。然后确认 .env 不会进 Git：
cd ~/code/dongge-web
git check-ignore .env.env，说明它被忽略了。如果没有任何输出，先把 .env 加进 .gitignore 再继续。开分支，安装 SDK
git switch main
git pull
git switch -c feat/ai-ask
npm install @anthropic-ai/sdkserver-only 在 DAY 47 已经装过，不用再装。
package.json 的 dependencies 里多了 @anthropic-ai/sdk，并且 server-only 还在。用一个小脚本确认 Key 能用
在接进网站之前，先用最短的代码确认“Key 对、网络通、账户有额度”。新建文件：
dongge-web/scripts/hello-claude.mjs
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const message = await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
messages: [{ role: "user", content: "用一句话介绍你自己。" }],
});
console.log("stop_reason:", message.stop_reason);
if (message.stop_reason !== "refusal") {
for (const block of message.content) {
if (block.type === "text") console.log(block.text);
}
}
console.log("usage:", message.usage);运行（--env-file 让 Node 读取 .env）：
node --env-file=.env scripts/hello-claude.mjs这个脚本故意只用最基础的写法，方便你第一次看清请求和响应；网站里的正式接口会再加上 beta 接口和 fallbacks。
stop_reason: end_turn，然后是一句中文自我介绍，最后是 input_tokens 和 output_tokens。去 Console 的 Usage 页面，过几分钟能看到这次调用。在 CLAUDE.md 写下 AI 功能约定
这是给 Claude 的长期规矩，以后每次它改 AI 相关代码都会先读。打开项目根目录的 CLAUDE.md（没有就新建），在末尾加上：
dongge-web/CLAUDE.md
## AI 功能约定
- 只在服务端调用 Claude：Route Handler 或 Server Action。客户端组件里不许出现 @anthropic-ai/sdk 和 ANTHROPIC_API_KEY。
- 客户端对象统一用 lib/ai/claude.ts 的 getClaude()；模型名只用 MODEL 常量，不在别处写死。
- 所有请求走 client.beta.messages，带 betas: [FALLBACK_BETA] 和 fallbacks: "default"。
- 不传 temperature、top_p、top_k。
- 读 content 之前先检查 stop_reason：refusal 给友好提示；max_tokens 说明被截断。
- 长输出用流式（client.beta.messages.stream）。
- 所有 AI 接口先检查管理员登录，再用 Zod 校验输入，最后才调用 Claude。
- 写 @anthropic-ai/sdk 代码前先查官方文档，不凭记忆写参数。写需求卡
新建文件夹 docs/specs，写今天的需求卡：
dongge-web/docs/specs/day55-ask.md
# 需求：最小 AI 接口 /api/ai/ask
## 背景
后台要接入 Claude。今天先打通一条最短的链路，确认密钥、SDK、登录检查都正常。
## 要做
- 新建 lib/ai/claude.ts：导出 MODEL、FALLBACK_BETA、getClaude()（懒创建，缺 Key 时报中文错误）。
- 新建 lib/ai/reply.ts：readReply(message)，先查 stop_reason，再拼接 text 块。
- 复用 DAY 47 的 lib/admin.ts：接口用 getAdminSession()（返回 401），页面用 requireAdmin()。不修改 lib/admin.ts。
- 新建 POST /api/ai/ask：输入 { question }，返回 { answer, truncated, servedBy, usage }。
- 新建后台页面 /admin/ai：一个输入框、一个按钮，显示回答或错误。
## 不做
- 不做流式输出、不做对话历史（明天做）。
- 不改前台页面，不改数据库。
## 验收标准
- [ ] 未登录时 curl 调用接口，返回 401。
- [ ] 登录后在 /admin/ai 提问，能看到中文回答。
- [ ] 提交空内容返回 400 和提示；超过 500 字也返回 400。
- [ ] 代码里读取 ANTHROPIC_API_KEY 的地方只有 lib/ai/claude.ts。
- [ ] npm run build 成功，且 .next/static 里搜不到 sk-ant。
- [ ] 请求参数里没有 temperature；有 fallbacks: "default"。
## 约束
遵守 CLAUDE.md 的「AI 功能约定」。让 Claude 在 Plan 模式出方案，你来审方案
在 Claude Code 里切到 Plan 模式，发送本页「问 Claude」里的第一条提示词。拿到方案后，对照需求卡检查三件事：文件清单是否和“要做”一致；有没有出现“不做”里的内容；有没有提到先查文档。不满意就直接说哪里要改，满意再让它执行。
逐文件审查 diff
git status
git diff --stat
git diff对照上午第 5、6 节的参考代码读每个文件。重点看：import "server-only" 在不在；MODEL 是否只定义一次；接口里的顺序是否是“登录、校验、调用”；有没有先判断 stop_reason。再搜一下 Key 出现在哪：
grep -rn "ANTHROPIC_API_KEY" app components liblib/ai/claude.ts 一处。按验收标准亲手验证
启动开发服务器 npm run dev，另开一个终端标签，先测未登录：
curl -i -X POST http://localhost:3000/api/ai/ask \
-H "Content-Type: application/json" \
-d '{"question":"你好"}'然后在浏览器登录后台，打开 http://localhost:3000/admin/ai，问一句“用一句话介绍斯诺克”。再试空内容。最后停掉开发服务器，检查构建产物：
npm run build
grep -rl "sk-ant" .next/static || echo "浏览器代码里没有 Key"HTTP/1.1 401；页面上出现中文回答；空内容显示“说点什么吧”；最后一条命令输出“浏览器代码里没有 Key”。把需求卡里的验收框逐个勾上。把线上 Key 加到 Vercel，提交并合并
打开 Vercel 的 dongge-web 项目，进入 Settings 里的 Environment Variables，新增 ANTHROPIC_API_KEY，值填第 2 步的 dongge-web-prod，环境只勾 Production。然后提交：
git add .
git status
git commit -m "feat: 接入 Claude 最小接口 /api/ai/ask"
git push -u origin feat/ai-ask
gh pr create --fillgit status 那一步要确认列表里没有 .env。如果你平时在 GitHub 网页上开 PR，也可以照旧。等 CI 变绿再合并。
/admin/ai 能得到回答。.env 没重启开发服务器。Next.js 只在启动时读取 .env，改完要按 Ctrl + C 停掉再 npm run dev。.env 不在项目根目录（要和 package.json 同级），或者变量名拼错。线上报这个错，说明 Vercel 里没加变量，或者加完没有重新部署。client.messages 而不是 client.beta.messages，或者测试版标记拼错；后者是代码里传了采样参数，删掉即可。"use client" 文件 import 了 lib/ai/claude.ts。客户端组件只能通过 fetch("/api/ai/ask") 调接口，不能直接用 SDK。这个报错正是 server-only 在保护你。API Key 如果写进浏览器端代码，会发生什么？
浏览器端代码会原样下载到每个访客的电脑上，任何人打开开发者工具的 Sources 或 Network 面板就能看到这串 Key。拿到 Key 的人可以用你的账户无限调用 Claude，费用记在你头上，直到你撤销这把 Key 或碰到用量上限。所以 Key 只能放在 .env，只在 Route Handler 或 Server Action 里读取；变量名不能加 NEXT_PUBLIC_；服务端文件用 server-only 防止被客户端引入；再用 Console 的用量上限兜底。
接口收到的响应里 stop_reason 是 "refusal"，你的代码会怎么做？为什么不能直接读 content[0].text？
readReply 会直接返回失败和一句友好提示，接口回 422，前端显示“换个说法再试”。不能直接读 content[0].text 有两个原因：被拒绝时 content 可能是空数组或只有半截内容；而且就算正常，第一块也可能是 thinking 或 fallback 块，不是文字。开启 fallbacks 后，最终仍是 refusal 说明主模型和备用模型都拒绝了。
一次调用的 usage 是 input_tokens: 800、output_tokens: 2000，按本地文档的 Opus 5 价格大约多少钱？如果一天调用 30 次呢？
800 × 5 ÷ 1000000 = 0.004 美元，2000 × 25 ÷ 1000000 = 0.05 美元，合计约 0.054 美元。一天 30 次约 1.62 美元。输出（含思考）比输入贵 5 倍，所以控制输出长度比压缩输入更省钱。价格以官方价格页为准。
client.beta.messages.stream 读取 Claude 的事件，转成一行一个 JSON 的小协议推给浏览器。getReader 和 TextDecoder 逐段读取，让回答一个字一个字地出现。AbortController 做一个“停止”按钮，并确认服务端也同时停止向 Claude 要内容。refusal）、被截断（max_tokens）和网络出错三种意外。昨天的 /api/ai/ask 是“一次性”接口：浏览器发出请求后，要等 Claude 把整段话写完，服务端才把结果一次性交回来。回答短的时候没问题，长一点就要盯着“思考中……”等十几秒，你会怀疑是不是卡住了。
流式输出（streaming）像是站在开放式厨房前看厨师做菜：第一道工序一开始你就看到了，虽然整道菜花的时间没变，但你一直知道“在做、做到哪了”。技术上说，流式输出就是服务端不等全部写完，每生成一小段就立刻发出去，浏览器收到一段就显示一段。
这里有一个重要的指标叫首字时间（Time To First Token，简称 TTFT）：从你按下发送到看见第一个字，过了多久。一次性接口的首字时间等于全部生成时间；流式接口的首字时间只是“开始写第一句”的时间。人对等待的感受主要取决于首字时间和“有没有进展”，所以流式会让人感觉快很多。
除了感受，还有一个硬性原因：输出很长时，一次性请求可能超过网络或平台的超时限制。SDK 在你把 max_tokens 设得非常大时，甚至会直接要求你改用流式。所以 CLAUDE.md 里写了“长输出用流式”。
调用 client.beta.messages.stream(...) 后，Claude 不是一次给你一整段文字，而是按顺序发来一连串“事件”。按本地文档，事件类型有这几种：
| 事件 | 什么时候来 | 我们关心吗 |
|---|---|---|
message_start | 开头一次，带模型名等信息 | 一般不用 |
content_block_start | 每个内容块开始时 | 用来发现兜底切换的 fallback 块 |
content_block_delta | 每来一小段内容 | 最重要，text_delta 里是新文字 |
content_block_stop | 每个内容块结束时 | 不用 |
message_delta | 接近结尾，带 stop_reason 和用量 | 用 finalMessage() 统一读取 |
message_stop | 结尾一次 | 不用 |
读取它们的写法是 for await 循环，DAY 22 学过 await 等待一个结果，for await 就是“来一个处理一个，直到没有为止”：
const aiStream = getClaude().beta.messages.stream({ /* 参数和昨天一样 */ });
for await (const event of aiStream) {
if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
console.log(event.delta.text); // 新来的一小段文字
}
}
const final = await aiStream.finalMessage(); // 完整的消息，包含 stop_reason 和 usage逐行看：第一行发起流式请求，但不会等它结束；循环里每拿到一个事件就判断类型，只有“内容增量”并且是“文字增量”时才取出文字，因为 Opus 5 默认会先思考，思考块也会产生增量事件，我们不需要它；循环结束后调用 finalMessage()，拿到和昨天一样的完整消息对象，stop_reason 就在里面。文档特别提醒：想要完整消息就用 finalMessage()，不要自己去拼。
服务端拿到了事件流，下一步是把它“转播”给浏览器。Web 标准里有一个现成的东西叫 ReadableStream（可读流），你可以把它想成一根水管：服务端往里面一段一段地放数据（enqueue），浏览器从另一头一段一段地接。Route Handler 返回 new Response(水管)，Next.js 就会边放边发。
为什么不直接把文字塞进水管？因为除了文字，我们还要告诉浏览器几件事：“备用模型接手了”“结束了，停止原因是什么”“出错了”。所以我们约定一个很小的协议：每行一个 JSON，行和行之间用换行符分开。这种格式有个名字叫 NDJSON（换行分隔的 JSON）。先把事件的类型写成一个前后端共用的文件：
dongge-web/lib/ai/stream-events.ts
// 服务端推给浏览器的每一行，都是下面四种之一
export type StreamEvent =
| { type: "text"; text: string } // 新来的一段文字
| { type: "notice"; text: string } // 提示，比如备用模型接手了
| { type: "done"; stopReason: string | null } // 结束，附带 stop_reason
| { type: "error"; text: string }; // 出错了这个文件只有类型，没有密钥，所以前后端都能引入，不需要 server-only。再准备聊天用的系统提示词：
dongge-web/lib/ai/prompts.ts
export const CHAT_SYSTEM_PROMPT = `你是东哥的写作助手，帮他想选题、改文案、理清想法。
东哥是短视频博主「三岁的东哥」，观众主要是女性。
回答用简体中文，先给结论，保持简短；需要列点时不超过 5 点。
这是实时对话，请直接开始回答。`;最后一句来自本地文档对 Opus 5 的建议：在对首字时间敏感的场景里，明确告诉它直接开始回答，可以减少开口前的思考时间。下面是完整的接口：
dongge-web/app/api/ai/chat/route.ts
import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { getAdminSession } from "@/lib/admin";
import { getClaude, MODEL, FALLBACK_BETA } from "@/lib/ai/claude";
import { CHAT_SYSTEM_PROMPT } from "@/lib/ai/prompts";
import type { StreamEvent } from "@/lib/ai/stream-events";
export const maxDuration = 60;
const ChatInput = z.object({
messages: z
.array(
z.object({
role: z.enum(["user", "assistant"]),
content: z.string().min(1).max(8000),
}),
)
.min(1)
.max(20)
.refine((list) => list.at(-1)?.role === "user", "最后一条必须是你的提问")
.refine((list) => (list.at(-1)?.content.length ?? 0) <= 1000, "提问最多 1000 字"),
});
const encoder = new TextEncoder();
function encode(event: StreamEvent) {
return encoder.encode(JSON.stringify(event) + "\n");
}
export async function POST(request: Request) {
const session = await getAdminSession();
if (!session) {
return Response.json({ error: "请先登录后台" }, { status: 401 });
}
const parsed = ChatInput.safeParse(await request.json().catch(() => null));
if (!parsed.success) {
return Response.json({ error: parsed.error.issues[0].message }, { status: 400 });
}
const aiStream = getClaude().beta.messages.stream(
{
model: MODEL,
max_tokens: 16000,
betas: [FALLBACK_BETA],
fallbacks: "default",
system: CHAT_SYSTEM_PROMPT,
messages: parsed.data.messages,
},
{ signal: request.signal },
);
let cancelled = false;
const body = new ReadableStream<Uint8Array>({
async start(controller) {
try {
for await (const event of aiStream) {
if (event.type === "content_block_start" && event.content_block.type === "fallback") {
controller.enqueue(encode({ type: "notice", text: "主模型没有接这个请求，已自动换备用模型继续。" }));
}
if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
controller.enqueue(encode({ type: "text", text: event.delta.text }));
}
}
const final = await aiStream.finalMessage();
controller.enqueue(encode({ type: "done", stopReason: final.stop_reason }));
} catch (error) {
if (!cancelled && !(error instanceof Anthropic.APIUserAbortError)) {
console.error("流式生成出错", error);
controller.enqueue(encode({ type: "error", text: "生成出错了，请稍后再试。" }));
}
} finally {
if (!cancelled) controller.close();
}
},
cancel() {
cancelled = true;
console.log("客户端停止了生成");
aiStream.abort();
},
});
return new Response(body, {
headers: {
"Content-Type": "application/x-ndjson; charset=utf-8",
"Cache-Control": "no-store",
},
});
}逐段解释：
maxDuration = 60：Next.js 的路由配置，告诉部署平台这个接口最多可以运行 60 秒。具体上限以 Vercel 文档为准。ChatInput：前端每次会把完整历史发来（API 不记事），所以校验的是一个数组。最多 20 条，单条最多 8000 字（Claude 的回答可能较长），但最后一条必须是你的提问，且不超过 1000 字。list.at(-1) 取最后一个元素，?. 防止数组为空时报错。encode：把一个事件对象变成“JSON 加换行”，再用 TextEncoder 转成字节，因为水管里流的是字节。stream(参数, { signal: request.signal })：第二个参数是请求选项。request.signal 会在浏览器断开时触发，SDK 收到后就中止对 Claude 的请求。start(controller)：水管建好后立刻执行。循环里遇到 fallback 块就发一条提示；遇到文字增量就发文字；循环结束后读 finalMessage()，把 stop_reason 作为最后一行发出去。catch：如果是用户主动停止引起的 APIUserAbortError，什么都不发；其他错误打印到服务器日志，并给浏览器发一条不泄露细节的错误行。cancel()：浏览器那头不接了（点了停止、关了页面）时，运行环境会调用它。我们记下 cancelled，然后 aiStream.abort() 通知 SDK 停止。之后就不能再往已关闭的水管里写东西，所以 finally 里要先判断。浏览器这头，fetch 返回的 res.body 就是水管的出口。昨天用的 await res.json() 会等水管里的水全部流完才解析，那就不是流式了。今天要用 getReader() 拿到一个“读取器”，循环调用 reader.read()，每次拿到一小块字节。
这里有两个细节新手最容易漏：
new TextDecoder() 配合 decode(value, { stream: true })，会把不完整的半个字先留着，等下一块来了再拼上。buffer 变量攒着，按换行符切开，最后那段不完整的先留在 buffer 里，其余完整的行逐个 JSON.parse。dongge-web/app/admin/ai/chat/chat-box.tsx
"use client";
import { useRef, useState } from "react";
import type { StreamEvent } from "@/lib/ai/stream-events";
type Msg = { role: "user" | "assistant"; content: string };
export default function ChatBox() {
const [messages, setMessages] = useState<Msg[]>([]);
const [input, setInput] = useState("");
const [loading, setLoading] = useState(false);
const [notice, setNotice] = useState("");
const controllerRef = useRef<AbortController | null>(null);
function appendToLast(text: string) {
setMessages((prev) => {
const last = prev[prev.length - 1];
return [...prev.slice(0, -1), { ...last, content: last.content + text }];
});
}
function handleEvent(event: StreamEvent) {
if (event.type === "text") {
appendToLast(event.text);
} else if (event.type === "notice" || event.type === "error") {
setNotice(event.text);
} else if (event.type === "done") {
if (event.stopReason === "refusal") {
// 中途被拒：已经显示的半截内容不可靠，整条丢掉
setMessages((prev) => prev.slice(0, -1));
setNotice("这次回答被安全机制拦下了，不完整的内容已丢弃。换个说法再试。");
} else if (event.stopReason === "max_tokens") {
setNotice("回答太长，被截断了。");
}
}
}
async function send() {
const text = input.trim();
if (!text || loading) return;
// 历史里去掉空的回答（被停止或被拒绝时可能留下）
const history: Msg[] = [...messages.filter((m) => m.content), { role: "user", content: text }];
setMessages([...history, { role: "assistant", content: "" }]);
setInput("");
setNotice("");
setLoading(true);
const controller = new AbortController();
controllerRef.current = controller;
try {
const res = await fetch("/api/ai/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ messages: history }),
signal: controller.signal,
});
if (!res.ok || !res.body) {
const data = await res.json().catch(() => null);
throw new Error(data?.error ?? "请求失败");
}
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop() ?? "";
for (const line of lines) {
if (line.trim()) handleEvent(JSON.parse(line) as StreamEvent);
}
}
} catch (error) {
if (controller.signal.aborted) {
setNotice("已停止。");
} else {
setNotice(error instanceof Error ? error.message : "出错了");
}
} finally {
setLoading(false);
controllerRef.current = null;
}
}
function stop() {
controllerRef.current?.abort();
}
return (
<div className="space-y-4">
<div className="space-y-3">
{messages.map((m, i) => (
<div key={i} className={m.role === "user" ? "text-right" : ""}>
<p
className={`inline-block max-w-[85%] whitespace-pre-line rounded-lg px-3 py-2 text-left ${
m.role === "user" ? "bg-black text-white" : "bg-gray-100"
}`}
>
{m.content || (loading && i === messages.length - 1 ? "……" : "")}
</p>
</div>
))}
</div>
{notice && <p className="text-sm text-gray-500">{notice}</p>}
<div className="flex gap-2">
<textarea
value={input}
onChange={(e) => setInput(e.target.value)}
maxLength={1000}
rows={2}
className="flex-1 rounded border p-2"
placeholder="说点什么"
/>
{loading ? (
<button type="button" onClick={stop} className="rounded border px-4">停止</button>
) : (
<button type="button" onClick={send} className="rounded bg-black px-4 text-white">发送</button>
)}
</div>
</div>
);
}重点解释几处：
setMessages([...history, 空回答])：先放一条空的 assistant 消息占位，之后每来一段文字就用 appendToLast 接到它后面，这就是“逐字出现”的来源。appendToLast 用的是函数式更新 setMessages((prev) => ...)。文字来得很快，一秒钟可能更新几十次，函数式更新保证每次都基于最新的列表，不会丢字（DAY 29 讲过 state 更新不是立即生效的）。useRef 存 AbortController：它不需要显示在页面上，改变它也不需要重新渲染，所以用 ref 而不是 state。key：DAY 28 说过下标做 key 在重新排序时会出问题，而聊天记录只会在末尾追加，不会重排，所以可以接受。页面文件很短，照 DAY 47 的约定，第一行检查管理员：
dongge-web/app/admin/ai/chat/page.tsx
import { requireAdmin } from "@/lib/admin";
import ChatBox from "./chat-box";
export default async function ChatPage() {
await requireAdmin();
return (
<div className="mx-auto max-w-2xl space-y-4 p-6">
<h1 className="text-2xl font-bold">和 Claude 对话</h1>
<ChatBox />
</div>
);
}AbortController 是浏览器自带的“取消遥控器”：new AbortController() 得到遥控器，把它的 signal 交给 fetch，之后调用 controller.abort()，这次请求就被取消。点“停止”之后依次发生：
controller.abort()，reader.read() 抛出错误，进入 catch，因为 signal.aborted 为真，显示“已停止”。已经显示的半截回答保留在页面上。request.signal 被触发，同时水管的 cancel() 被调用。aiStream.abort() 让 SDK 中止对 Claude 的请求，Claude 不再继续生成。钱的问题：停止之前已经生成的输出照常计费，停止之后的不再产生。所以“停止”既是体验功能，也是省钱功能。我们同时用了 request.signal 和 cancel() 两条路，是为了在不同运行环境下都能可靠地停下来。
stop_reason 是 refusal，已经流出来的半截内容不可靠，应该丢弃，不能当成完整回答。我们开启了 fallbacks，大多数误判会被备用模型接住：流里会出现一个 fallback 类型的内容块作为分界，之后是备用模型继续写的内容，前面的内容不会被撤回。只有主模型和备用模型都拒绝时，最终才是 refusal，前端这时删掉那条回答。stop_reason 是 max_tokens，内容是完整的前半段，提示用户即可。error，前端显示提示；如果连接直接断了，前端的 catch 会接住。昨天你学了需求卡的六块结构。今天的难点在于：流式这种功能，“看起来能用”和“真的是流式”可能是两回事。比如 Claude 写的前端如果用了 await res.json()，页面照样能显示回答，只是要等全部写完才一下子出来。你只看结果，很容易放过这个问题。
所以验收标准要写成能观察到的现象，并且想好用什么工具观察：
标准里的数字也有讲究。“停止要快”没法检验，“点停止后 1 秒内停止增长”就可以。数字不必精确到毫秒，但要让你和 Claude 对“过关”有同一个理解。
还有一条习惯要从今天养成：区分“Claude 说它做到了”和“我亲眼看到了”。Claude 可能会告诉你“已处理半行拼接”“测试已通过”，这些都只是它的描述。你的验收框只在你自己跑过命令、点过页面之后才能勾。审查今天的代码时，专门找这三个问题：前端有没有用 await res.json() 读流；有没有处理半行和半个汉字；done 行里是 refusal 时有没有丢弃内容。
开分支
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/ai-chat-stream写需求卡
dongge-web/docs/specs/day56-chat.md
# 需求：流式对话页 /admin/ai/chat
## 背景
一次性接口要等全部写完才显示，体验差。改成流式，并能中途停止。
## 要做
- 新建 lib/ai/stream-events.ts：StreamEvent 类型（text / notice / done / error）。
- 在 lib/ai/prompts.ts 新增 CHAT_SYSTEM_PROMPT。
- 新建 POST /api/ai/chat：接收完整历史 messages，用 client.beta.messages.stream 调用，
以 NDJSON（每行一个 JSON）推给浏览器；遇到 fallback 块推 notice；结束时推 done 和 stop_reason。
- 浏览器断开时中止对 Claude 的请求（request.signal 和 ReadableStream 的 cancel 都要处理）。
- 新建 /admin/ai/chat 页面和客户端组件 chat-box.tsx：逐字显示、停止按钮、提示区。
## 不做
- 不保存聊天记录到数据库。不做 Markdown 渲染。
## 验收标准
- [ ] 提一个需要长回答的问题，文字分多次出现，而不是最后一次性出现。
- [ ] 回答过程中点“停止”，文字在 1 秒内停止增长，页面显示“已停止”，服务器终端打印“客户端停止了生成”。
- [ ] 停止后可以继续发下一句，对话能接上前文。
- [ ] 未登录调用接口返回 401；最后一条超过 1000 字返回 400。
- [ ] done 行的 stopReason 为 refusal 时，前端删除这条回答并显示提示（用代码审查确认）。
- [ ] 中文不出现乱码或半个字。
## 约束
遵守 CLAUDE.md 的「AI 功能约定」。Plan 模式出方案并审查
把「问 Claude」第一条发给 Claude。审方案时重点确认：它打算用 beta.messages.stream 而不是 create；打算怎么处理半行；有没有说明 cancel() 里做什么。
让 Claude 实现，然后读 diff
git diff --stat
git diff app/api/ai/chat/route.ts对照上午第 3、4 节的参考代码，用下面的清单逐项打勾：登录检查在最前；fallbacks: "default" 和 betas 都在；没有 temperature；for await 里只转发 text_delta；有 finalMessage()；cancel() 调用了 abort()；前端用 getReader()、TextDecoder 和 buffer。说不清的地方让 Claude 解释给你听。
验证逐字显示
npm run dev，登录后打开 http://localhost:3000/admin/ai/chat，输入：“帮我列 5 个绅士世界的视频选题，每个写两句为什么适合。”再打开开发者工具的 Network 面板，点这次 chat 请求，看 Timing 里的 Content Download。
验证停止
再问一个长问题，文字出来两三行时点“停止”。切到运行 npm run dev 的终端看日志。
验证输入校验和登录检查
curl -i -X POST http://localhost:3000/api/ai/chat \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"你好"}]}'401。模拟一次“中途被拒”，确认前端逻辑
真实的拒绝很难故意触发，我们临时改一行代码来模拟。在 route.ts 里把 stopReason: final.stop_reason 暂时改成 stopReason: "refusal"，保存后提一个问题。
git diff 确认没有残留。看一眼用量
打开 Claude Console 的 Usage 页面，找到刚才被你停止的那次请求，对比一次完整回答的输出 token 数。
跑检查、提交、开 PR
npm run typecheck
npm test
npm run build
git add .
git commit -m "feat: 流式对话页，支持中途停止"
git push -u origin feat/ai-chat-stream
gh pr create --fill这三条命令和 DAY 53 配置的 CI 跑的一样，本地先过，CI 才会过。CI 通过后合并。
await res.json() 或 await res.text()，它们会等全部数据到齐；或者服务端用的是 create 而不是 stream。按第 4 节改成 getReader() 循环读取。buffer 攒着最后那段不完整的内容。decoder.decode(value) 少了 { stream: true }，汉字的字节被切在两块之间。cancel() 设置了 cancelled = true，并且 catch 和 finally 都先判断它。catch 里用 controller.signal.aborted 把它和真正的错误区分开，只显示“已停止”。为什么流式输出会让人感觉更快？
总生成时间并没有变短，变短的是“首字时间”：一次性接口要等全部写完才显示第一个字，流式接口在 Claude 写出第一小段时就显示出来了。人对等待的感受主要取决于多久看到第一个反馈、以及有没有持续的进展，看着文字一点点出现，就知道“在做、做到哪了”，不会怀疑卡住。另外，看到开头不对还能马上点停止，省时间也省钱。
点“停止”之后，从浏览器到 Claude 依次发生了什么？已经生成的部分要不要付钱？
前端调用 controller.abort()，fetch 的读取被中断，进入 catch 显示“已停止”；浏览器断开连接，服务端的 request.signal 被触发、水管的 cancel() 被调用；cancel() 里执行 aiStream.abort()，SDK 中止对 Claude 的请求，Claude 不再生成。停止前已经生成的输出照常计费，停止后的不再产生。
为什么服务端不直接把纯文字推给浏览器，而是每行一个 JSON？
因为除了文字，浏览器还需要知道其他信息：备用模型是否接手、生成是否正常结束、结束原因是不是 refusal 或 max_tokens、有没有出错。纯文字没法区分“这是回答的一部分”还是“这是一条控制信息”。每行一个 JSON，用 type 字段区分，前端就能分别处理；用换行分隔，也方便按行切开、处理半行的情况。
lib/ai/prompts.ts，每次修改都写明原因。昨天的对话页已经能流式回答了，但它的系统提示词只有四行，写出来的文案很普通。今天我们专门写一份给“文案助手”用的系统提示词。
想象你请了一位新的文案助理，他很聪明、读过很多书，但完全不认识你。第一天你会怎么交代？你会说你是谁、观众是谁、你喜欢什么样的文字、绝对不要什么，再拿两条你满意的旧文案给他看，最后告诉他交稿的格式。系统提示词就是这份入职说明，而且它有一个特点：助理每次干活前都会从头读一遍，并且只知道这份说明里写的东西。
所以写系统提示词时要记住一句话：凡是你没写的，模型只能靠猜。你觉得“东哥的风格大家都懂”，模型并不懂。你觉得“克制”两个字已经很清楚，模型对“克制”的理解可能和你差很远。
上一句的反面同样成立：写进去的每一句都会被认真执行，包括你随手写的、互相矛盾的话。所以提示词不是越长越好，而是每一句都要有用、不打架。
这五部分之间，我们用 <关于东哥>、<写作原则> 这样的标签隔开。标签不是什么特殊语法，只是让模型（和你自己）一眼看清哪段是背景、哪段是规则、哪段是例子，不会把示例里的句子当成规则。Claude 的官方提示词指南也推荐这种做法。
“说事情不说情话”是你的分寸，对你来说一听就懂。但对模型来说它太抽象了。要把它翻译成三层：
另一个技巧是多说“写什么”，少只说“不写什么”。只写“不要油腻”，模型知道要躲开什么，却不知道该往哪走；写“写他搞砸的一件小事”，它就有了方向。禁止项要留着，但每个禁止项旁边最好配一个替代做法。
女性观众视角也要翻译。与其写“要有女性视角”，不如直接告诉模型她们来看什么：看一个人认真做一件事，看他的小失误，看他照顾别人的细节。再给一个动作：“写之前先想，她刷到这条时，最可能停下来的是哪个瞬间，把那个瞬间写出来。”
还有一条容易被忽略：不编造。你给的主题是“帮新学员缠手带”，模型可能顺手编出“那个学员后来拿了冠军”。发出去就是假话。所以要求它不要把没发生的事写成事实，需要补细节时写成“镜头里能拍到的画面”，由你核对。
同一个主题，两个平台的读法完全不同。小红书的用户会点进笔记慢慢看文字，TikTok 的用户在刷视频，文字只是画面的配角。把差异落到可以检查的数字上：
| 小红书 | TikTok | |
|---|---|---|
| 标题 | 不超过 20 字，像日记里的一句话，可以留悬念 | 封面大字，不超过 12 字，一眼看懂 |
| 正文 | 150 到 300 字，3 到 5 段，第一句直接进场景 | 1 到 3 句，不超过 60 字，第一句就是画面里正在发生的事 |
| 标签 | 4 到 6 个，一半和世界有关，一半和生活有关 | 3 到 5 个，可以用英文 |
| 语气 | 像写给朋友的小日记 | 像视频里随口说的一句话 |
这些数字不是平台规定，而是你给自己定的风格。用一段时间后，你会根据真实数据调整它们，所以它们要集中写在一处，方便改。
下面是一份可以直接使用的版本。它放在 lib/ai/prompts.ts 里，拆成三块：COPY_RULES（人设、观众、原则、平台、示例，所有地方共用）、COPY_TEXT_OUTPUT（纯文字输出格式，给对话页用）和两者拼成的 COPY_CHAT_PROMPT。明天做结构化输出时，只需要换掉输出格式那一块。
dongge-web/lib/ai/prompts.ts（在昨天的 CHAT_SYSTEM_PROMPT 下面追加）
export const WORLD_BRIEFS = {
gentleman: { name: "绅士", feeling: "安全感", detail: "斯诺克，马甲、衬衫、皮鞋" },
street: { name: "街头", feeling: "心动", detail: "BMX 和滑板，Baggy 裤、Vans、Oversize" },
thai: { name: "泰风", feeling: "被保护感", detail: "泰拳和泰国元素，泰拳短裤" },
} as const;
export const COPY_RULES = `你是「三岁的东哥」的文案搭档，负责给他的短视频写发布文案。东哥会自己修改后再发布，所以你交出的是一版好改的草稿，不是定稿。
<关于东哥>
东哥是短视频博主，一句话人设：在外面是绅士、拳手、潮男，在你面前三岁。
他有三个世界，每条视频属于其中一个：
- 绅士：斯诺克，马甲、衬衫、皮鞋。给观众的感觉是安全感。
- 街头：BMX 和滑板，Baggy 裤、Vans、Oversize。给观众的感觉是心动。
- 泰风：泰拳和泰国元素，泰拳短裤。给观众的感觉是被保护感。
“在你面前三岁”指的是反差：场上认真、利落；放下那一面后，会犯迷糊、会把小事搞砸、会不好意思。写出这种反差，但不要装嫩，不要用叠词撒娇。
</关于东哥>
<观众>
观众大多是女性。她们刷到东哥，是想得到一点情绪价值：看到一个人认真做一件事，看到他的小失误，看到他照顾别人的细节。
写之前先想：她刷到这条时，最可能停下来的是哪个瞬间？把那个瞬间写出来。
</观众>
<写作原则>
1. 说事情，不说情话。写他做了什么、看到什么、手里拿着什么、哪里没做好。不写“宝贝”“想你”“你是我的”这类称呼和句子，不写土味情话，不直接夸观众。原因：情话会让观众觉得被推销、被油到；具体的事情才让人愿意相信这个人。
2. 具体。每条至少有一个具体细节：一个动作、一件物品、一个数字或一个地点。
3. 克制。少用感叹号，不堆形容词，不用网络流行口头禅。可以有一点自嘲。
4. 不编造。主题里没提到的经历，不要写成已经发生的事实；需要补细节时，写成镜头里能拍到的画面，东哥会自己核对。
</写作原则>
<平台差异>
小红书：
- 标题不超过 20 个字，像日记里的一句话，可以留一点悬念，不做标题党。
- 正文 150 到 300 字，分 3 到 5 段，每段一两句，第一句直接进入场景。
- 标签 4 到 6 个，一半和这个世界有关（如 斯诺克、BMX、泰拳），一半和生活有关（如 周末日常、男生穿搭）。
TikTok：
- 标题是视频封面上的大字，不超过 12 个字，一眼能看懂。
- 正文 1 到 3 句，合计不超过 60 个字，口语，第一句就是画面里正在发生的事。
- 标签 3 到 5 个，可以用英文（如 snooker、bmx、muaythai）。
</平台差异>
<示例>
下面两个例子只用来说明分寸，不要照抄其中的句子。
好的写法（街头，主题：雨后练车摔了）：
下午雨停了，场地还没干。第三次落地的时候后轮一滑，膝盖先着地。
坐在地上缓了一会儿，把车扶起来，发现脚踏也歪了。
回家路上买了一瓶冰水，一半喝了，一半敷在膝盖上。
不要这样写：
宝贝们！今天的我帅不帅！摔倒了也要帅给你们看！想不想被我保护！
问题：全是口号和情话，没有一件具体的事。
</示例>`;
export const COPY_TEXT_OUTPUT = `<输出要求>
先写小红书版，再写 TikTok 版。每版依次写：标题、正文、标签（标签前加 #）。
只输出草稿本身，不写开场白和解释。保持简短，写完就停。
</输出要求>`;
export const COPY_CHAT_PROMPT = `${COPY_RULES}\n\n${COPY_TEXT_OUTPUT}`;逐块解释：
WORLD_BRIEFS：三个世界的资料，写成对象方便明天按 gentleman 这样的 slug 取用。as const 让 TypeScript 把它当作固定不变的数据。${COPY_RULES} 这种写法把两段拼在一起。<关于东哥> 和 <观众> 是背景；<写作原则> 和 <平台差异> 是要求；<示例> 是示例；<输出要求> 是输出格式。本地文档专门提到了 Opus 5 的几个习惯，直接影响提示词写法：
提示词好不好，不能凭一次输出判断。模型每次的输出都会有些不同，一次写得好可能是运气。测试要像做实验：
docs/prompt-log.md。一周后你会感谢自己。“变差”也要有统一的尺子，不然你今天心情好就觉得都不错。先用五个“是或否”的问题检查每条输出：有没有情话或直接夸观众的句子；有没有至少一个具体细节；字数有没有超出平台要求；有没有照抄示例里的句子；有没有把主题里没有的事写成事实。每出现一个“坏”的答案记一次。删掉某一块后，“坏”的次数明显变多，就说明这一块在起作用。明天做正式评估时，我们会在这五个问题之外再加一个 1 到 5 分的整体打分。
在 L4 阶段，提示词本身是产品决定，应该由你来写：观众是谁、分寸在哪、什么叫好，只有你知道。Claude 可以帮你挑毛病、找含糊的地方，但最后改不改、怎么改，你来定。代码部分（加一个人设切换开关）照常写需求卡交给 Claude。明天我们把输出从纯文字升级为固定格式的“标题、正文、标签”。
开分支
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/copy-prompt先不看示例，自己写 15 分钟
拿一张纸或新建一个空白文件，按“角色、背景、要求、示例、输出格式”五块，写你心目中的文案助手说明。重点写“说事情不说情话”具体指什么，至少举一个你自己发过的、满意的文案做好例子。写完再和上午第 5 节的示例对比，把你写得更准确的部分替换进去。
把提示词写进 prompts.ts
这一步你自己动手，不交给 Claude。打开 lib/ai/prompts.ts，在 CHAT_SYSTEM_PROMPT 下面加上 WORLD_BRIEFS、COPY_RULES、COPY_TEXT_OUTPUT 和 COPY_CHAT_PROMPT，内容用你上一步定稿的版本。
写需求卡：给对话页加一个人设开关
dongge-web/docs/specs/day57-persona.md
# 需求：对话页支持切换“文案人设”
## 背景
要在对话页里反复测试文案系统提示词。
## 要做
- /api/ai/chat 的输入增加 persona 字段，取值 "assistant" 或 "copy"，默认 "assistant"（用 Zod 的 default）。
- persona 为 "copy" 时，system 用 lib/ai/prompts.ts 的 COPY_CHAT_PROMPT；否则用 CHAT_SYSTEM_PROMPT。
- chat-box.tsx 顶部加一个下拉框：“通用助手 / 文案人设”，请求时带上 persona。
## 不做
- 不改 prompts.ts 里的提示词内容（那是我写的）。
- 不做提示词在线编辑。
## 验收标准
- [ ] 选“文案人设”，输入“街头：第一次练滑板 ollie 失败”，回答依次包含小红书版和 TikTok 版，每版有标题、正文、带 # 的标签。
- [ ] 选“通用助手”，同样的输入得到的是普通回答，不是两版文案。
- [ ] persona 传一个不存在的值（比如 "abc"）时接口返回 400。
- [ ] git diff 里 prompts.ts 只有我自己的改动。
## 约束
遵守 CLAUDE.md 的「AI 功能约定」。让 Claude 实现并审查
把「问 Claude」第二条发给 Claude。实现后读 diff，你应该看到类似这样的改动：
dongge-web/app/api/ai/chat/route.ts（改动部分）
import { CHAT_SYSTEM_PROMPT, COPY_CHAT_PROMPT } from "@/lib/ai/prompts";
const ChatInput = z.object({
persona: z.enum(["assistant", "copy"]).default("assistant"),
messages: z
.array(/* 和昨天一样 */)
// ……
});
// 调用时：
system: parsed.data.persona === "copy" ? COPY_CHAT_PROMPT : CHAT_SYSTEM_PROMPT,dongge-web/app/admin/ai/chat/chat-box.tsx（改动部分）
const [persona, setPersona] = useState<"assistant" | "copy">("assistant");
// 请求体里带上 persona：
body: JSON.stringify({ persona, messages: history }),
// 界面最上方：
<select
value={persona}
onChange={(e) => setPersona(e.target.value as "assistant" | "copy")}
className="rounded border p-2"
>
<option value="assistant">通用助手</option>
<option value="copy">文案人设</option>
</select>git diff lib/ai/prompts.ts 里没有 Claude 改动的痕迹。如果它“顺手优化”了你的提示词，让它撤回。用 3 个固定主题测试，每个跑两次
npm run dev，在对话页选“文案人设”。每个主题新开一次对话（刷新页面即可清空），依次输入：
绅士：打斯诺克时给对手递巧粉
街头：第一次练滑板 ollie 失败
泰风：泰拳课后帮新学员拆手带新建 docs/prompt-log.md，按下面的格式记录。每条输出只记要点，不用全文复制：
dongge-web/docs/prompt-log.md
# 提示词实验记录
## v1 完整版（日期）
- 绅士/递巧粉：有具体动作（擦巧粉、递过去），无情话；小红书 280 字，偏长。
- 街头/ollie：第二次运行出现一句“想被我接住吗”，算情话。
- 泰风/拆手带：TikTok 正文 2 句，合格。做“删一句对比”实验
每次只删一块，保存后用同样的 3 个主题各跑一次，记录结果，然后恢复原样再删下一块。建议依次试这四处：
<示例> 块<观众> 块<平台差异> 块恢复时可以用 git diff lib/ai/prompts.ts 确认改回去了，或者直接 git checkout lib/ai/prompts.ts（前提是你已经把完整版提交过一次）。
prompt-log.md 里有 v1 完整版和 4 次删减版的记录，你能说出删掉哪一块后变差最明显。请 Claude 挑毛病，由你决定改不改
把「问 Claude」第一条发给 Claude。对它的每条意见，在 prompt-log.md 里写一行：接受或不接受，理由是什么。接受的改动做成 v2，再用 3 个主题跑一轮。
提交
npm run typecheck
npm test
npm run build
git add .
git commit -m "feat: 文案系统提示词和对话页人设切换"
git push -u origin feat/copy-prompt
gh pr create --filltemperature 去压随机性，新模型不接受这个参数。你的提示词里，删掉哪一句后输出变差得最明显？
答案因人而异，要用你 prompt-log.md 里的实验结果回答，并说清“变差”具体指什么。一个常见的结果是：删掉原则 1 的“原因”或删掉示例之后，情话和空泛的形容词明显变多，因为模型失去了判断分寸的依据；删掉平台差异后，TikTok 版变得和小红书一样长。好的回答会包含：删了哪一块、用了哪 3 个主题各跑几次、出现了什么具体问题（比如 6 次里有 3 次出现“宝贝”），以及你打算怎样保护这一句。
为什么“不写情话”这条规则后面要加上“原因”？只写规则不行吗？
只写规则，模型只能按字面执行，遇到规则没列出的情况就容易走偏，比如不写“宝贝”，却写出“今天也想被你看见”这种换了说法的情话。写出原因（情话会让人觉得被推销，具体的事才可信），模型就能理解背后的目的，自己判断新句子是否越界。原因也方便你以后回看：这条规则为什么存在，能不能改。
小红书和 TikTok 的文案，在标题、正文、标签上各有什么不同？为什么？
小红书用户会点进来慢慢读，标题像日记里的一句话、不超过 20 字，正文 150 到 300 字分几段，标签 4 到 6 个兼顾世界和生活；TikTok 用户在刷视频，文字是画面的配角，标题是封面大字、不超过 12 字，正文 1 到 3 句不超过 60 字、第一句就是画面里的事，标签 3 到 5 个可以用英文。差异来自阅读场景：一个是读文字，一个是看画面顺便扫一眼文字。
client.beta.messages.parse 拿到有类型的结果。昨天在对话页里，“文案人设”已经能写出两版草稿了，但它输出的是一整段文字。今天要做的文案助手页面，需要把标题、正文、标签分别放进卡片的不同位置，明天还要分别存进数据库。
如果让程序从一整段文字里“切”出标题和正文，会非常脆弱：Claude 可能这次写“标题：”，下次写“【标题】”，偶尔还在前面加一句“好的，以下是草稿”。你写的切分代码只要遇到一次意外格式就会出错。
打个比方：让人写一封信，每个人的写法都不一样；让人填一张表，每一栏写什么、写在哪就固定了。结构化输出（structured outputs）就是给 Claude 一张“表”：你用 JSON Schema（一种描述 JSON 长什么样的规范）告诉它必须返回哪些字段、每个字段是什么类型，API 在生成时就被约束在这个结构里，返回的一定是能解析的 JSON。
对你来说，好处有三点：不用写切字符串的代码；拿到的数据有 TypeScript 类型，写错字段名编辑器会提醒；字段固定，存数据库、做界面都简单。
它是怎么做到的？可以把 Claude 写字想象成每一步都从很多候选字里挑一个。开启结构化输出后，API 会在每一步把“会让 JSON 不合格式”的候选直接划掉：该写逗号的地方不能写句号，必填字段没写完之前不能结束。所以它不是“写完再检查”，而是“写的时候就只能按格式写”。这也说明了它管不了什么：格式能保证，内容写得好不好、字数多不多，仍然要靠提示词。
DAY 44 你用 Zod 校验过表单输入。Zod 还能反过来生成 JSON Schema，SDK 提供的辅助函数会帮你完成这一步，所以我们只需要写 Zod：
dongge-web/lib/ai/copy-schema.ts
import { z } from "zod";
export const WORLD_SLUGS = ["gentleman", "street", "thai"] as const;
// Claude 要填写的表：每个平台一版草稿
const PlatformDraft = z.object({
title: z.string().describe("标题。小红书不超过 20 个字；TikTok 是封面大字，不超过 12 个字"),
body: z.string().describe("正文，分段用换行表示"),
tags: z.array(z.string()).describe("话题标签，不带 # 号"),
});
export const CopyResult = z.object({
xiaohongshu: PlatformDraft,
tiktok: PlatformDraft,
});
export type CopyResult = z.infer<typeof CopyResult>;
// 你在表单里填写的内容
export const CopyInput = z.object({
world: z.enum(WORLD_SLUGS),
topic: z.string().trim().min(2, "主题至少 2 个字").max(60, "主题最多 60 个字"),
});
export type CopyInput = z.infer<typeof CopyInput>;逐段解释：
PlatformDraft：一版草稿有三栏，title 和 body 是字符串，tags 是字符串数组。.describe() 给每一栏写一句说明，这句说明会跟着 Schema 一起发给 Claude，相当于表格每一栏旁边的小字提示。CopyResult：整张表有两个字段，xiaohongshu 和 tiktok，结构相同。z.infer：从 Schema 自动推导出 TypeScript 类型，同一个名字既是校验规则也是类型，不用手写两遍。CopyInput：用户输入的校验。世界只能是三个 slug 之一，主题 2 到 60 个字。这是昨天说的“输入长度限制”的第一道防线，也在控制成本。SDK 会把上面的 Zod 转成类似下面的 JSON Schema 发给 API（为了好读，tiktok 部分省略了，它和 xiaohongshu 一样）：
{
"type": "object",
"properties": {
"xiaohongshu": {
"type": "object",
"properties": {
"title": { "type": "string", "description": "标题。小红书不超过 20 个字；TikTok 是封面大字，不超过 12 个字" },
"body": { "type": "string", "description": "正文，分段用换行表示" },
"tags": { "type": "array", "items": { "type": "string" }, "description": "话题标签，不带 # 号" }
},
"required": ["title", "body", "tags"],
"additionalProperties": false
}
},
"required": ["xiaohongshu", "tiktok"],
"additionalProperties": false
}读法：type 是类型；properties 列出每个字段；required 表示这些字段一个都不能少；additionalProperties: false 表示不许多出表格里没有的字段。你不用手写这段，但要能看懂，因为出错时报错信息里常常会提到它。
你可能会问：为什么不给 title 加 .max(20)？官方文档写明，结构化输出不支持 maxLength、minimum 这类数值限制。SDK 会把这些限制从发出的 Schema 里去掉、改写进字段说明里，拿到结果后再在本地用 Zod 检查一遍，不符合就直接报错。标题写了 21 个字，整次生成就作废了，钱也白花了。所以输出 Schema 只管结构，字数这类要求交给提示词，超出一点由你在编辑时修改。
本地 SDK 文档里结构化输出的基本写法是 client.messages.parse(...)，配合 zodOutputFormat(Schema) 放在 output_config.format 里，结果在 response.parsed_output。我们的所有请求都要开启服务端兜底，而兜底是测试版功能，只在 client.beta 下面，所以换成对应的测试版写法：client.beta.messages.parse 配合 betaZodOutputFormat（从 @anthropic-ai/sdk/helpers/beta/zod 引入）。两者用法一样，只是一个在 beta 下面。
dongge-web/lib/ai/generate-copy.ts
import "server-only";
import Anthropic from "@anthropic-ai/sdk";
import { betaZodOutputFormat } from "@anthropic-ai/sdk/helpers/beta/zod";
import { getClaude, MODEL, FALLBACK_BETA } from "@/lib/ai/claude";
import { COPY_JSON_PROMPT, WORLD_BRIEFS } from "@/lib/ai/prompts";
import { CopyResult, type CopyInput } from "@/lib/ai/copy-schema";
export type GenerateResult =
| { ok: true; data: CopyResult; usage: { input: number; output: number } }
| { ok: false; message: string };
export async function generateCopy(input: CopyInput): Promise<GenerateResult> {
const world = WORLD_BRIEFS[input.world];
const userPrompt = [
`世界：${world.name}（${world.detail}；给人的感觉：${world.feeling}）`,
`视频主题：${input.topic}`,
"请写小红书和 TikTok 各一版草稿。",
].join("\n");
try {
const message = await getClaude().beta.messages.parse({
model: MODEL,
max_tokens: 16000,
betas: [FALLBACK_BETA],
fallbacks: "default",
system: COPY_JSON_PROMPT,
messages: [{ role: "user", content: userPrompt }],
output_config: { format: betaZodOutputFormat(CopyResult) },
});
// 先看 stop_reason，再读结果
if (message.stop_reason === "refusal") {
return { ok: false, message: "这个主题被安全机制拒绝了，换个说法试试。" };
}
if (message.stop_reason === "max_tokens") {
return { ok: false, message: "输出被截断了，请再试一次。" };
}
if (!message.parsed_output) {
return { ok: false, message: "没有拿到草稿，请重试。" };
}
return {
ok: true,
data: message.parsed_output,
usage: { input: message.usage.input_tokens, output: message.usage.output_tokens },
};
} catch (error) {
if (error instanceof Anthropic.APIError) {
console.error("Claude API 出错", error.status, error.message);
return { ok: false, message: "AI 服务暂时不可用，稍后再试。" };
}
if (error instanceof Anthropic.AnthropicError) {
// SDK 解析或校验 JSON 失败，多半是输出被截断成了半截 JSON
console.error("结构化输出解析失败", error.message);
return { ok: false, message: "这次生成的格式不完整，请再试一次。" };
}
throw error;
}
}逐段解释：
userPrompt：用数组加 join("\n") 拼出三行文字。世界的资料来自昨天写的 WORLD_BRIEFS，主题来自用户。长期规则在系统提示词里，这一次的具体任务在用户消息里。output_config.format：把 Zod Schema 交给 SDK，它会转成 JSON Schema 发给 API，并在返回后自动解析、校验，结果放在 message.parsed_output，类型就是 CopyResult。parsed_output，这就是 CLAUDE.md 里“先看 stop_reason”的规矩。parsed_output 可能是 null（比如被拒时没有内容），所以还要判断一次。APIError 是网络和服务的问题（Key 错、限流、过载）。AnthropicError 是 SDK 的通用错误，SDK 解析 JSON 失败时抛的就是它，常见原因是输出写到上限被截成了半截 JSON。APIError 本身也是 AnthropicError 的一种，所以必须先判断更具体的 APIError，顺序反了就永远进不了第一个分支。GenerateResult 又是一个成功或失败的联合类型，调用方必须先看 ok。兜底和结构化输出能一起用吗？能。主模型拒绝、备用模型接手时，备用模型收到的是同一份请求，包括同一个 Schema，所以返回的仍然是同样结构的 JSON。本地文档说明，非流式请求里被拒模型写了一半的内容不会出现在结果里，content 里只会多一个 fallback 类型的块标记换人的位置；SDK 解析时只看文字块，不受影响。想知道这次是谁写的，可以在服务器日志里打印 message.model。
昨天我们特意把提示词拆成了 COPY_RULES 和输出格式两块，今天只需要加一个 JSON 版的输出格式：
dongge-web/lib/ai/prompts.ts（追加）
export const COPY_JSON_OUTPUT = `<输出要求>
按给定的 JSON 结构返回：xiaohongshu 和 tiktok 各一版，每版包含 title（标题）、body（正文）、tags（标签）。
正文分段用换行表示。标签不要带 # 号。
字段里只写草稿内容，不写解释或备注。保持简短。
</输出要求>`;
export const COPY_JSON_PROMPT = `${COPY_RULES}\n\n${COPY_JSON_OUTPUT}`;结构本身由 Schema 保证，这里说的是“每一栏里该写什么”：标签不带 # 号，是因为页面显示时会统一加上；不写备注，是防止它在正文里夹一句“（可根据实际情况修改）”。对话页继续用纯文字版 COPY_CHAT_PROMPT，两边共用同一份规则，改规则时两边一起生效。
文案助手是一个表单：选世界、填主题、点生成。DAY 43 学过，表单提交最自然的做法是 Server Action。这里为什么不用昨天的流式接口？因为结构化输出要等 JSON 完整才能解析，边写边显示半截 JSON 没有意义；而且两版草稿加起来只有几百字，等待时给一个明确的“生成中”提示就够了。如果以后输出变长或遇到超时，SDK 也支持用 stream() 生成结构化输出，再用 finalMessage() 取结果。
dongge-web/app/admin/ai/copy/actions.ts
"use server";
import { getAdminSession } from "@/lib/admin";
import { CopyInput, type CopyResult } from "@/lib/ai/copy-schema";
import { generateCopy } from "@/lib/ai/generate-copy";
export type CopyFormState =
| { status: "idle" }
| { status: "error"; message: string }
| { status: "done"; topic: string; result: CopyResult };
export async function generateCopyAction(
_prev: CopyFormState,
formData: FormData,
): Promise<CopyFormState> {
const session = await getAdminSession();
if (!session) {
return { status: "error", message: "请先登录后台" };
}
const parsed = CopyInput.safeParse({
world: formData.get("world"),
topic: formData.get("topic"),
});
if (!parsed.success) {
return { status: "error", message: parsed.error.issues[0].message };
}
const result = await generateCopy(parsed.data);
if (!result.ok) {
return { status: "error", message: result.message };
}
return { status: "done", topic: parsed.data.topic, result: result.data };
}和 DAY 47 讲的一样：Server Action 本质上是一个可以被直接调用的接口，所以第一件事仍然是检查登录，然后 Zod 校验，最后才调用 Claude。返回的 CopyFormState 有三种状态，页面据此显示不同内容。
为什么出错时 return 一个状态，而不是 throw 一个错误？抛出去的错误会被 Next.js 的错误页接住，整页变成“出错了”，你刚填的主题也没了；返回一个 error 状态，页面和表单都还在，只是多一行红字，改一下就能再试。第一个参数 _prev 是上一次的状态，useActionState 规定它必须排在第一位，我们用不到它，名字前加下划线表示“故意不用”。
dongge-web/app/admin/ai/copy/copy-form.tsx
"use client";
import { useActionState } from "react";
import { generateCopyAction, type CopyFormState } from "./actions";
const initialState: CopyFormState = { status: "idle" };
const WORLDS = [
{ slug: "gentleman", label: "绅士 · 安全感" },
{ slug: "street", label: "街头 · 心动" },
{ slug: "thai", label: "泰风 · 被保护感" },
];
type Draft = { title: string; body: string; tags: string[] };
export default function CopyForm() {
const [state, formAction, pending] = useActionState(generateCopyAction, initialState);
return (
<div className="space-y-6">
<form action={formAction} className="space-y-4">
<fieldset className="flex flex-wrap gap-4">
<legend className="mb-2 font-medium">选一个世界</legend>
{WORLDS.map((w, i) => (
<label key={w.slug} className="flex items-center gap-2">
<input type="radio" name="world" value={w.slug} defaultChecked={i === 0} />
{w.label}
</label>
))}
</fieldset>
<label className="block">
<span className="font-medium">视频主题</span>
<input
name="topic"
maxLength={60}
required
className="mt-1 w-full rounded border p-2"
placeholder="例如：第一次打满一局斯诺克，最后一颗黑球没进"
/>
</label>
<button disabled={pending} className="rounded bg-black px-4 py-2 text-white disabled:opacity-50">
{pending ? "生成中，大约需要半分钟……" : "生成两版草稿"}
</button>
</form>
{state.status === "error" && <p className="text-red-600">{state.message}</p>}
{state.status === "done" && (
<div className="grid gap-4 md:grid-cols-2">
<DraftCard platform="小红书" draft={state.result.xiaohongshu} />
<DraftCard platform="TikTok" draft={state.result.tiktok} />
</div>
)}
</div>
);
}
function DraftCard({ platform, draft }: { platform: string; draft: Draft }) {
return (
<article className="rounded-lg border p-4">
<p className="text-sm text-gray-500">{platform}</p>
<h2 className="mt-1 text-lg font-bold">{draft.title}</h2>
<p className="mt-2 whitespace-pre-line">{draft.body}</p>
<p className="mt-3 text-sm text-gray-600">{draft.tags.map((t) => `#${t}`).join(" ")}</p>
</article>
);
}useActionState 是 React 提供的钩子：传入 Server Action 和初始状态，得到当前状态 state、交给表单的 formAction，以及“是否正在提交”的 pending。pending 为真时按钮变灰并显示提示，这同时防止了连点重复提交（DAY 44 做过同样的事）。whitespace-pre-line 让正文里的换行真的显示成换行。
dongge-web/app/admin/ai/copy/page.tsx
import { requireAdmin } from "@/lib/admin";
import CopyForm from "./copy-form";
export const maxDuration = 60;
export default async function CopyPage() {
await requireAdmin();
return (
<div className="mx-auto max-w-4xl space-y-6 p-6">
<h1 className="text-2xl font-bold">文案助手</h1>
<p className="text-gray-600">选一个世界，写一句视频主题，生成小红书和 TikTok 两版草稿。</p>
<CopyForm />
</div>
);
}页面第一行照 DAY 47 的约定调用 requireAdmin()。maxDuration 写在页面上，对这个页面触发的 Server Action 同样有效，给生成留出足够时间。Action 里用的是 getAdminSession() 并返回错误状态，而不是会跳转的 requireAdmin()，这样登录过期时表单会显示一句提示，而不是突然跳走。
功能做完不等于做好了。文案助手好不好，最终要看它写的东西你愿不愿意发。今天的验收就是一次小型评估：选 5 个真实主题（最好是你接下来真的要拍的视频），每个生成一次，给两版草稿分别打 1 到 5 分：
| 分数 | 含义 |
|---|---|
| 5 | 可以直接发 |
| 4 | 改一两处就能发 |
| 3 | 方向对，但要大改 |
| 2 | 只有个别句子能用 |
| 1 | 不能用：油腻、跑题或编造 |
打分之外，再用昨天的五个检查项（情话、具体细节、字数、照抄示例、编造）逐条过一遍，把发现的问题写下来。记录问题比记录分数更重要：明天你要根据这些问题改提示词，只写“3 分”是没法改的，写“TikTok 标题 15 个字，超了；正文第二句是空泛的形容”才有用。
打分前先定好标准，并且对 5 个主题用同一把尺子。如果打到第三条时你觉得标准该调整，就把前两条也按新标准重打一遍。
为什么强调真实主题？因为自己编的测试题往往太“好写”，比如“帅气地打一局斯诺克”，模型很容易写得像模像样；真实主题常常很琐碎，比如“鞋底磨穿了”，这才考验它能不能从小事里写出情绪。打分时先只看文案本身，不要先想“上一条打了几分”，尽量减少先入为主。5 个主题的样本很小，平均分只能当参考，真正有价值的是反复出现的问题。
结构化输出的代码量不大，但有几处 Claude 容易写错，审查时逐一核对：
client.beta.messages.parse 和 betaZodOutputFormat，而不是自己 JSON.parse 文字。自己解析等于放弃了 SDK 的校验。parsed_output 之前有没有先判断 stop_reason。catch 里 APIError 是否在 AnthropicError 前面。.max() 之类的限制。title、body、tags）。最后一条值得多想一下：字段名一旦定下来，以后要改就得同时改 Schema、提示词、页面、数据库和测试五处。所以审查时把自己当成明天写数据库的人，现在觉得名字不顺手，就趁今天改。
失败分支怎么亲手验证？一个实用的办法是临时把 max_tokens 改得很小（比如 300），让输出必然被截断，看页面是否显示“格式不完整”或“被截断”的提示。验证完立刻改回 16000。明天我们把草稿存进数据库，并加上每天的次数限制。
开分支，确认 Zod 版本
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/copy-assistant
npm ls zodSDK 的 Zod 辅助函数需要 Zod 4 的写法。如果显示的是 3.x 版本，先运行 npm install zod@latest，再跑一次 npm test，确认 DAY 44 写的校验规则都还能通过。
npm ls zod 显示的主版本号是 4。自己追加 JSON 版输出格式
提示词仍然由你负责。打开 lib/ai/prompts.ts，照上午第 4 节追加 COPY_JSON_OUTPUT 和 COPY_JSON_PROMPT。
写需求卡
dongge-web/docs/specs/day58-copy.md
# 需求：文案助手 /admin/ai/copy
## 背景
选一个世界、输入视频主题，一次生成小红书和 TikTok 两版草稿，字段固定为标题、正文、标签。
## 要做
- lib/ai/copy-schema.ts：CopyResult（xiaohongshu、tiktok 各含 title、body、tags）和 CopyInput（world 三选一，topic 2 到 60 字）。
- lib/ai/generate-copy.ts：generateCopy(input)，用 client.beta.messages.parse + betaZodOutputFormat，
system 用 COPY_JSON_PROMPT。先查 stop_reason（refusal、max_tokens），再读 parsed_output。
APIError 和 SDK 解析失败分别给中文提示。返回 { ok, data, usage } 或 { ok: false, message }。
- app/admin/ai/copy/actions.ts：generateCopyAction，先查登录，再 Zod 校验，再调用 generateCopy。
- app/admin/ai/copy/page.tsx 和 copy-form.tsx：用 useActionState；生成中按钮禁用；结果显示两张卡片，标签前加 #。
## 不做
- 不存数据库、不做次数限制（明天做）。
- 输出 Schema 不加长度限制。
- 不改 prompts.ts 里的内容。
## 验收标准
- [ ] 选“街头”、填“Vans 鞋底磨穿了还舍不得扔”，半分钟内显示两张卡片，各有标题、正文、标签。
- [ ] 主题只填 1 个字，提示“主题至少 2 个字”，且没有调用 Claude（Console 用量不增加）。
- [ ] 生成中按钮是灰的，连点不会发出第二次请求。
- [ ] 临时把 max_tokens 改成 300，页面显示“格式不完整”或“被截断”的提示；改回后恢复正常。
- [ ] 代码里没有手写的 JSON.parse 处理 Claude 的输出。
## 约束
遵守 CLAUDE.md 的「AI 功能约定」。Plan、实现、审查
把「问 Claude」第一条发给 Claude。方案里要确认它会用 betaZodOutputFormat，并说明 catch 里两种错误的判断顺序。实现后按上午第 7 节的清单审查 diff：
git diff --stat
git diff lib/ai
grep -rn "JSON.parse" lib appgrep 的结果里没有用来解析 Claude 输出的 JSON.parse（聊天页前端解析 NDJSON 的那一处是正常的）。跑通正常流程
npm run dev，打开 http://localhost:3000/admin/ai/copy，选“街头”，主题填“Vans 鞋底磨穿了还舍不得扔”，点生成。
验证失败分支
先试输入校验：主题只填“拳”，点生成。再试截断：把 generate-copy.ts 里的 max_tokens: 16000 临时改成 300，保存后再生成一次。
git diff lib/ai/generate-copy.ts 确认。准备评估表
新建评估记录文件，把打分标准写在最上面，免得打分时标准跑偏：
dongge-web/docs/copy-eval.md
# 文案助手评估
评分：5 直接能发 / 4 改一两处能发 / 3 方向对但要大改 / 2 个别句子能用 / 1 不能用
检查项：情话、具体细节、字数、照抄示例、编造
## 第 1 轮（提示词 v2，日期）
| # | 世界 | 主题 | 小红书 | TikTok | 问题 |
|---|------|------|--------|--------|------|
| 1 | 绅士 | 第一次打满一局斯诺克，最后一颗黑球没进 | | | |
| 2 | 绅士 | 给朋友的婚礼挑一件马甲 | | | |
| 3 | 街头 | 雨后空场地练 BMX，摔了三次 | | | |
| 4 | 街头 | Vans 鞋底磨穿了还舍不得扔 | | | |
| 5 | 泰风 | 泰拳课后帮新学员缠手带 | | | |
平均分：小红书 TikTok表里的主题是示例，最好换成你接下来一两周真的要拍的 5 个视频。
逐个生成、打分、记录问题
每个主题生成一次，把两版草稿复制到一个临时文档里备查（明天有了数据库就不用手动复制了）。打分后在“问题”一栏写具体现象，例如“TikTok 标题 15 字，超了”“小红书第三段在夸观众”。
让 Claude 帮你归纳问题
把「问 Claude」第三条发给 Claude。它的归纳只作参考，明天改提示词时，由你决定先解决哪一类问题。
提交
npm run typecheck
npm test
npm run build
git add .
git commit -m "feat: 文案助手，结构化输出两个平台草稿"
git push -u origin feat/copy-assistant
gh pr create --fill/admin/ai/copy 能生成草稿。npm ls zod 查版本，升级到 4 后重跑测试。max_tokens 是否被改小了没改回；再看输出 Schema 有没有加 .max()、.min() 之类的限制，Claude 多写一个字就会让本地校验失败，删掉这些限制。client.beta.messages.parse，而不是 client.messages.parse；确认 betas 里是 FALLBACK_BETA 常量，没有手打错。page.tsx 里有 maxDuration。Opus 5 默认会先思考再作答，半分钟左右是正常的；明天会介绍用 effort 降低思考量来提速省钱的实验。COPY_JSON_OUTPUT 里有没有写“标签不要带 # 号”；页面上也可以用 t.replace(/^#/, "") 去掉开头的 #，双保险。用 5 个真实主题测试，每条输出打 1–5 分，记下问题。
交付物是填好的 docs/copy-eval.md：5 个主题、10 个分数、两个平台各自的平均分，每个低于 5 分的格子都有具体问题。一份合格的记录大概像这样：“街头/Vans 鞋底：小红书 4 分，第二段‘这双鞋陪我走过很多路’太空泛，没有具体细节；TikTok 3 分，标题 14 字超出 12 字，正文第一句不是画面。”再在表格下写一两句总结，比如“TikTok 标题超长出现 3 次，是最常见的问题”，这就是明天改提示词的依据。
结构化输出和“在提示词里要求按格式写、再用代码切字符串”相比好在哪里？用了结构化输出，还需要检查 stop_reason 吗？
结构化输出在生成时就被约束在 Schema 里，返回的一定是字段固定、能解析的 JSON，不会出现“有时写标题：有时写【标题】”或多一句开场白的情况；SDK 还会自动解析和校验，并给出 TypeScript 类型。但仍然要检查 stop_reason：被拒绝时可能没有内容，parsed_output 是 null；写到上限被截断时 JSON 不完整，SDK 解析会失败。所以顺序是先看 stop_reason，再读 parsed_output，并在 catch 里处理解析失败。
为什么输出 Schema 里不给 title 加 .max(20)？字数要求靠什么来保证？
结构化输出不支持 maxLength 这类限制。SDK 会把它从发出的 Schema 里去掉，改写进字段说明，再在拿到结果后用 Zod 本地校验，只要超出一个字就会报错，整次生成作废、费用白花。所以输出 Schema 只描述结构，字数要求写在系统提示词和字段说明里，偶尔超出由人工编辑时修正。用户输入的 CopyInput 则可以放心加长度限制，因为那是在调用 Claude 之前检查的。
Draft 和 AiUsage，每次生成后自动把两版草稿存进数据库。max_tokens；并知道 effort 和提示词缓存各适合什么情况。昨天的文案助手有个明显的问题：生成的草稿只显示在页面上，一刷新就没了。钱花了，结果没留下，你还得手动复制到备忘录里。今天把它们存进数据库，做成一个草稿箱。
设计表之前，先问自己“以后会怎么用这些数据”：
再加上成本控制，我们需要一张记录“每次调用 Claude 用了多少 token”的表。这样“过去 24 小时用了几次”“这周大概花了多少钱”都能从数据库里算出来，不用每次去 Console 查。
同样重要的是想清楚不存什么。我们不存 Claude 返回的完整原始响应，也不存系统提示词的全文，只存你以后真正会用的字段。存得越多，表越乱，以后改结构越麻烦。原则是：先存最少的，确实需要时再加列，加列只是一次小迁移。
dongge-web/prisma/schema.prisma（追加，并修改 World）
enum DraftPlatform {
XIAOHONGSHU
TIKTOK
@@map("draft_platform")
}
enum DraftStatus {
DRAFT
PUBLISHED
@@map("draft_status")
}
model Draft {
id Int @id @default(autoincrement())
platform DraftPlatform
topic String
title String
body String
tags String[]
favorite Boolean @default(false)
status DraftStatus @default(DRAFT)
publishedAt DateTime? @map("published_at")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @map("updated_at")
worldId Int @map("world_id")
world World @relation(fields: [worldId], references: [id])
@@index([createdAt])
@@map("drafts")
}
model AiUsage {
id Int @id @default(autoincrement())
feature String
inputTokens Int @map("input_tokens")
outputTokens Int @map("output_tokens")
createdAt DateTime @default(now()) @map("created_at")
@@index([createdAt])
@@map("ai_usage")
}
// 在已有的 model World { ... } 里加一行：
// drafts Draft[]逐项解释：
platform 分别是小红书和 TikTok。为什么不把两版放在同一行？因为你会分别收藏、分别修改、分别发布，拆开更自然。enum：枚举，限定只能取几个固定值。DAY 50 的提问箱状态也是这么做的，数据库会拒绝写入别的值。tags String[]：PostgreSQL 支持数组类型，标签直接存成字符串数组，不用另建一张标签表。自用的小工具，够用就好。status 加 publishedAt：为什么不用一个 published 布尔值？状态枚举以后可以加“已排期”之类的新状态；publishedAt 记下发布时间，复盘时能和那一周的点击数据对照。DateTime? 的问号表示可以为空，没发布就是空。@updatedAt：每次修改时 Prisma 自动更新这个时间。worldId 和 world：外键关系，和 DAY 41 设计的 looks 指向 worlds 一样。worldId 是 Int，和 DAY 42 里 World 的 id 一致。Prisma 要求关系两边都写，所以 World 里要加 drafts Draft[]。@map 和 @@map：沿用 DAY 42 定的规矩，代码里用驼峰（createdAt、Draft），数据库里用小写加下划线（created_at、drafts），枚举类型也一样（draft_status）。以后直接写 SQL 统计时，用的是数据库里的名字。@@index([createdAt])：两张表都经常按时间查（最新的草稿、过去 24 小时的用量），加索引让查询更快（DAY 41 讲过索引）。AiUsage.feature：记录是哪个功能用的，"copy" 或 "chat"。改完 schema 后要做两件事：生成迁移并应用到开发数据库，再重新生成 Prisma Client。Prisma 7 起，migrate dev 不再自动运行 generate，所以要自己跑，具体以 Prisma 官方文档为准。
npx prisma migrate dev --name add-draft-and-ai-usage
npx prisma generate先写一个管用量的小模块：
dongge-web/lib/ai/usage.ts
import "server-only";
import { prisma } from "@/lib/prisma";
// 过去 24 小时最多调用多少次（文案和对话合计）
export const DAILY_LIMIT = 30;
export async function usedInLast24h() {
const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
return prisma.aiUsage.count({ where: { createdAt: { gte: since } } });
}
export async function recordUsage(
feature: "copy" | "chat",
usage: { input: number; output: number },
) {
await prisma.aiUsage.create({
data: { feature, inputTokens: usage.input, outputTokens: usage.output },
});
}为什么用“过去 24 小时”而不是“今天”？“今天”要先决定按哪个时区算零点，服务器在 UTC，你可能在别的时区，容易出错。“过去 24 小时”是一个滚动的窗口，不涉及时区，对防止用超了来说效果一样。
然后改写昨天的 Server Action：
dongge-web/app/admin/ai/copy/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { prisma } from "@/lib/prisma";
import { getAdminSession } from "@/lib/admin";
import { CopyInput, type CopyResult } from "@/lib/ai/copy-schema";
import { generateCopy } from "@/lib/ai/generate-copy";
import { DAILY_LIMIT, recordUsage, usedInLast24h } from "@/lib/ai/usage";
export type CopyFormState =
| { status: "idle" }
| { status: "error"; message: string }
| { status: "done"; topic: string; result: CopyResult; draftIds: number[]; remaining: number };
export async function generateCopyAction(
_prev: CopyFormState,
formData: FormData,
): Promise<CopyFormState> {
const session = await getAdminSession();
if (!session) {
return { status: "error", message: "请先登录后台" };
}
// 第一道闸：输入长度（CopyInput 里限制了主题 2 到 60 字）
const parsed = CopyInput.safeParse({
world: formData.get("world"),
topic: formData.get("topic"),
});
if (!parsed.success) {
return { status: "error", message: parsed.error.issues[0].message };
}
// 第二道闸：过去 24 小时的次数，在花钱之前检查
const used = await usedInLast24h();
if (used >= DAILY_LIMIT) {
return { status: "error", message: `过去 24 小时已用 ${used} 次，达到上限，晚点再来。` };
}
const world = await prisma.world.findUnique({ where: { slug: parsed.data.world } });
if (!world) {
return { status: "error", message: "找不到这个世界，请检查种子数据。" };
}
// 第三道闸 max_tokens 在 generateCopy 里
const result = await generateCopy(parsed.data);
if (!result.ok) {
return { status: "error", message: result.message };
}
const { topic } = parsed.data;
const { xiaohongshu, tiktok } = result.data;
const drafts = await prisma.$transaction([
prisma.draft.create({ data: { platform: "XIAOHONGSHU", topic, worldId: world.id, ...xiaohongshu } }),
prisma.draft.create({ data: { platform: "TIKTOK", topic, worldId: world.id, ...tiktok } }),
]);
await recordUsage("copy", result.usage);
revalidatePath("/admin/drafts");
return {
status: "done",
topic,
result: result.data,
draftIds: drafts.map((d) => d.id),
remaining: DAILY_LIMIT - used - 1,
};
}重点看顺序：登录、校验、限额、查世界，全部通过之后才调用 Claude。任何一步不通过都直接返回，不花一分钱。保存用 prisma.$transaction([...])，意思是“两条要么都成功，要么都不写”，不会出现只存了小红书、TikTok 丢了的半截状态。...xiaohongshu 是 DAY 17 学过的展开运算符，把 title、body、tags 三个字段直接铺进去，因为 Schema 的字段名和数据库一致，这里一行就够了（这就是昨天说要审查字段名的原因）。
为什么 recordUsage 放在保存草稿之后？如果保存失败（比如数据库暂时连不上），这次调用就不会被记录，次数会少算一次。反过来放在前面，保存失败时次数照记，但你什么也没拿到。两种都有道理，对自用工具来说差别不大，关键是你知道这里有一个取舍，而不是随手一放。审查代码时，多问一句“这两行为什么是这个顺序”，常常能发现问题。
对话接口也要接入同样的限额，在 app/api/ai/chat/route.ts 里加两处：
import { DAILY_LIMIT, recordUsage, usedInLast24h } from "@/lib/ai/usage";
// 在 Zod 校验之后、调用 Claude 之前：
if ((await usedInLast24h()) >= DAILY_LIMIT) {
return Response.json({ error: "过去 24 小时的 AI 次数已用完" }, { status: 429 });
}
// 在 start() 里，拿到 finalMessage 之后：
const final = await aiStream.finalMessage();
await recordUsage("chat", { input: final.usage.input_tokens, output: final.usage.output_tokens });429 是 HTTP 里“请求太多”的状态码。被中途停止的对话拿不到 finalMessage，不会被记录，这是一个小漏洞，自用可以接受。
三道闸各管一件事：输入长度管单次的输入量，也防止有人把一整篇文章塞进来；次数上限管总量，就算代码写出死循环，最多也只能调用 30 次；max_tokens 管单次的输出上限。再往外，还有 DAY 55 在 Console 设的每月用量上限，那是最后一道保险丝。
AiUsage 表里有每次的 token 数，你可以随时估算花费。在 Neon 的 SQL 编辑器里运行：
SELECT count(*) AS calls,
sum(input_tokens) AS input_tokens,
sum(output_tokens) AS output_tokens,
round(sum(input_tokens) * 5 / 1000000.0 + sum(output_tokens) * 25 / 1000000.0, 2) AS usd
FROM ai_usage
WHERE created_at >= now() - interval '7 days';这条 SQL 按本地文档的 Opus 5 单价（输入每百万 5 美元、输出每百万 25 美元）估算最近 7 天的花费。表名 ai_usage 和列名 input_tokens 都是 schema 里 @@map、@map 指定的名字。实际账单以 Console 为准。
两个进阶手段，了解原理，按需使用：
low、medium、high、xhigh、max 五档，默认是 high。本地文档特别提到，这个模型在 low 和 medium 档表现很好，是降低成本和等待时间的主要手段。写法是在 output_config 里加一项：output_config: { effort: "medium", format: betaZodOutputFormat(CopyResult) }。要不要改，用评估说话：同样 5 个主题，对比分数和 outputTokens，分数不降就值得换。这一节想让你记住的是：省钱手段不是越多越好，要看你的使用方式。
草稿箱的三个操作都是 Server Action，放在同一个文件里：
dongge-web/app/admin/drafts/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { z } from "zod";
import { prisma } from "@/lib/prisma";
import { requireAdmin } from "@/lib/admin";
export async function toggleFavorite(id: number) {
await requireAdmin();
const draft = await prisma.draft.findUnique({ where: { id }, select: { favorite: true } });
if (!draft) return;
await prisma.draft.update({ where: { id }, data: { favorite: !draft.favorite } });
revalidatePath("/admin/drafts");
}
export async function setPublished(id: number, published: boolean) {
await requireAdmin();
await prisma.draft.update({
where: { id },
data: published
? { status: "PUBLISHED", publishedAt: new Date() }
: { status: "DRAFT", publishedAt: null },
});
revalidatePath("/admin/drafts");
}
const DraftEdit = z.object({
id: z.coerce.number().int().positive(),
title: z.string().trim().min(1, "标题不能为空").max(60, "标题最多 60 字"),
body: z.string().trim().min(1, "正文不能为空").max(2000, "正文最多 2000 字"),
tags: z.string().max(200, "标签太长了"),
});
export async function updateDraft(formData: FormData) {
await requireAdmin();
const parsed = DraftEdit.safeParse(Object.fromEntries(formData));
if (!parsed.success) {
throw new Error(parsed.error.issues[0].message);
}
const { id, title, body, tags } = parsed.data;
await prisma.draft.update({ where: { id }, data: { title, body, tags: splitTags(tags) } });
revalidatePath("/admin/drafts");
redirect("/admin/drafts");
}
function splitTags(raw: string) {
return raw
.split(/[\s,，#]+/)
.map((t) => t.trim())
.filter(Boolean)
.slice(0, 8);
}几处说明：每个 Action 第一行都是 DAY 47 写的 requireAdmin()，不是管理员就跳去登录页，理由和 DAY 48 删除操作要再查登录一样。z.coerce.number() 把表单里的字符串 "12" 转成数字 12。编辑页的标签是一个输入框，用空格、逗号或 # 分隔都行，splitTags 把它切成数组，去掉空的，最多留 8 个。这里校验失败直接抛错，后台自用问题不大；想要表单上的友好提示，可以照 DAY 44 的做法改成 useActionState。
dongge-web/app/admin/drafts/page.tsx
import Link from "next/link";
import { requireAdmin } from "@/lib/admin";
import { prisma } from "@/lib/prisma";
import { setPublished, toggleFavorite } from "./actions";
const PLATFORM_LABEL = { XIAOHONGSHU: "小红书", TIKTOK: "TikTok" } as const;
export default async function DraftsPage({
searchParams,
}: {
searchParams: Promise<{ filter?: string }>;
}) {
await requireAdmin();
const { filter } = await searchParams;
const where =
filter === "favorite"
? { favorite: true }
: filter === "published"
? { status: "PUBLISHED" as const }
: filter === "draft"
? { status: "DRAFT" as const }
: {};
const drafts = await prisma.draft.findMany({
where,
include: { world: true },
orderBy: { createdAt: "desc" },
take: 50,
});
return (
<div className="mx-auto max-w-4xl space-y-4 p-6">
<h1 className="text-2xl font-bold">草稿箱</h1>
<nav className="flex gap-3 text-sm">
<Link href="/admin/drafts">全部</Link>
<Link href="/admin/drafts?filter=favorite">收藏</Link>
<Link href="/admin/drafts?filter=draft">未发布</Link>
<Link href="/admin/drafts?filter=published">已发布</Link>
</nav>
{drafts.length === 0 && <p className="text-gray-500">这里还没有草稿。</p>}
<ul className="space-y-3">
{drafts.map((d) => (
<li key={d.id} className="rounded-lg border p-4">
<p className="text-sm text-gray-500">
{PLATFORM_LABEL[d.platform]} · {d.world.name} · {d.topic}
{d.status === "PUBLISHED" && " · 已发布"}
</p>
<h2 className="mt-1 font-bold">{d.title}</h2>
<p className="mt-1 line-clamp-2 text-gray-700">{d.body}</p>
<div className="mt-3 flex gap-2 text-sm">
<form action={toggleFavorite.bind(null, d.id)}>
<button className="rounded border px-3 py-1">{d.favorite ? "取消收藏" : "收藏"}</button>
</form>
<Link href={`/admin/drafts/${d.id}`} className="rounded border px-3 py-1">编辑</Link>
<form action={setPublished.bind(null, d.id, d.status !== "PUBLISHED")}>
<button className="rounded border px-3 py-1">
{d.status === "PUBLISHED" ? "改回未发布" : "标记已发布"}
</button>
</form>
</div>
</li>
))}
</ul>
</div>
);
}新东西是 toggleFavorite.bind(null, d.id)：bind 会生成一个“已经填好第一个参数”的新函数，交给表单的 action。点按钮时，Next.js 调用它，id 就是这一行草稿的编号。筛选用的是网址参数 ?filter=favorite，和 DAY 50 按状态筛选提问是同一个思路。line-clamp-2 让正文只显示两行。
dongge-web/app/admin/drafts/[id]/page.tsx
import { notFound } from "next/navigation";
import { requireAdmin } from "@/lib/admin";
import { prisma } from "@/lib/prisma";
import { updateDraft } from "../actions";
export default async function EditDraftPage({ params }: { params: Promise<{ id: string }> }) {
await requireAdmin();
const { id } = await params;
const draftId = Number(id);
if (!Number.isInteger(draftId)) notFound();
const draft = await prisma.draft.findUnique({ where: { id: draftId }, include: { world: true } });
if (!draft) notFound();
return (
<form action={updateDraft} className="mx-auto max-w-xl space-y-4 p-6">
<h1 className="text-xl font-bold">编辑草稿 · {draft.world.name}</h1>
<input type="hidden" name="id" value={draft.id} />
<label className="block">
标题
<input name="title" defaultValue={draft.title} maxLength={60} className="mt-1 w-full rounded border p-2" />
</label>
<label className="block">
正文
<textarea name="body" defaultValue={draft.body} rows={10} maxLength={2000} className="mt-1 w-full rounded border p-2" />
</label>
<label className="block">
标签（用空格分隔）
<input name="tags" defaultValue={draft.tags.join(" ")} className="mt-1 w-full rounded border p-2" />
</label>
<button className="rounded bg-black px-4 py-2 text-white">保存</button>
</form>
);
}网址里的 id 是字符串，先转成数字；转不成整数（比如有人访问 /admin/drafts/abc）就显示 404，免得把奇怪的值交给数据库。
昨天的评估表里记下了问题。改提示词的步骤：
docs/prompt-log.md：改了什么、为了解决哪个问题。举例：如果“TikTok 标题超过 12 字”出现了 3 次，可以在平台差异的 TikTok 部分加一句具体的例子：“标题像一句很短的旁白，比如‘差一颗黑球’，不要写成完整的句子。”例子往往比再强调一遍“不超过 12 个字”更管用。改完之后，TikTok 标题的问题次数从 3 次降到 0 次，而小红书没有变差，才能说这处改动有效。
5 个主题的样本很小，平均分差 0.2 分很可能只是运气。更可靠的信号是“某类问题的次数明显下降”。
提示词在 prompts.ts 里，它就是代码，Git 会记下每一个版本。建议每改一版提示词就单独提交一次，提交信息写清楚改了什么，比如“提示词 v3：TikTok 标题加例子”。哪天发现新版本整体变差，用 git log lib/ai/prompts.ts 找到上一版，就能退回去。prompt-log.md 记录“为什么改、效果如何”，Git 记录“具体改了哪几个字”，两者配合使用。
今天第一次让 Claude 改数据库结构，审查要多一步：读迁移文件。migrate dev 会在 prisma/migrations/ 下生成一个新文件夹，里面的 migration.sql 就是真正会在数据库上执行的 SQL。你在 DAY 40 学过这些语句，逐行读一遍：应该只有 CREATE TYPE、CREATE TABLE、CREATE INDEX 和添加外键的 ALTER TABLE。如果看到 DROP 或者修改了已有表的列，立刻停下来问清楚，这类改动可能丢数据。
正常的迁移文件大致是这样的片段（完整内容更长）：
-- CreateEnum
CREATE TYPE "draft_status" AS ENUM ('DRAFT', 'PUBLISHED');
-- CreateTable
CREATE TABLE "drafts" (
"id" SERIAL NOT NULL,
"title" TEXT NOT NULL,
"tags" TEXT[],
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
...
CONSTRAINT "drafts_pkey" PRIMARY KEY ("id")
);
-- AddForeignKey
ALTER TABLE "drafts" ADD CONSTRAINT "drafts_world_id_fkey" FOREIGN KEY ("world_id") REFERENCES "worlds"("id") ...;对照着读：SERIAL 是自增整数，对应 @default(autoincrement())；TEXT[] 是文本数组，对应 String[]；created_at 是 @map 翻译后的列名，TIMESTAMP(3) 是不带时区的时间（DAY 60 会讲它带来的时区问题）；最后一句给 world_id 加上外键约束，保证每条草稿指向的世界真实存在。每一句都能和 schema 里的一行对上，就说明迁移做的正是你想要的事。
第二个重点是检查“花钱之前”的顺序：每个会调用 Claude 的地方，都必须按“登录、校验、限额”的顺序通过之后才调用。你可以让 Claude 帮你扫一遍（「问 Claude」第二条），但结论要自己对照代码确认。
Draft 表。如果正式数据库还没有这张表，线上就会报错。所以合并前要先把迁移应用到正式数据库。明天我们开始做点击统计。开分支，写需求卡
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/draftsdongge-web/docs/specs/day59-drafts.md
# 需求：草稿保存、草稿箱和用量限制
## 背景
生成的草稿要保存下来反复修改；同时要限制每天的调用次数，控制成本。
## 要做
- schema：新增 DraftPlatform、DraftStatus 枚举，Draft、AiUsage 模型（字段见上午第 2 节，按 DAY 42 规矩用 @map、@@map），World 加 drafts 反向关系。
迁移名 add-draft-and-ai-usage。
- lib/ai/usage.ts：DAILY_LIMIT = 30，usedInLast24h()，recordUsage(feature, usage)。
- 文案 Action：限额检查放在调用 Claude 之前；成功后用事务保存两条 Draft，记录用量，返回 draftIds 和剩余次数。
- 对话接口：同样的限额检查（超出返回 429），结束后记录用量。
- /admin/drafts：列表（最新 50 条），全部/收藏/未发布/已发布筛选，收藏切换，标记已发布/改回未发布。
- /admin/drafts/[id]：编辑标题、正文、标签，Zod 校验后保存。
- 文案助手页面生成成功后显示剩余次数和“去草稿箱”链接。
## 不做
- 不做删除草稿。不做分页。不开提示词缓存。
## 验收标准
- [ ] 生成一次后，草稿箱多出两条（小红书、TikTok 各一条），世界和主题正确。
- [ ] 收藏、取消收藏、标记已发布、改回未发布都能生效，筛选结果正确；已发布的有发布时间。
- [ ] 修改标题和标签后保存，列表显示新内容；标签输入“斯诺克, 周末日常 #绅士”保存为三个标签。
- [ ] 把 DAILY_LIMIT 临时改成 1，第二次生成时提示达到上限，且 Console 用量没有增加；改回 30。
- [ ] 访问 /admin/drafts/abc 显示 404。
- [ ] migration.sql 里没有 DROP 语句。
## 约束
遵守 CLAUDE.md 的「AI 功能约定」。Plan 并在迁移处停一下
把「问 Claude」第一条发给 Claude。它生成迁移后会停下来给你看 migration.sql，你也可以自己打开：
ls prisma/migrations
cat prisma/migrations/*add-draft-and-ai-usage/migration.sqlDROP。确认后告诉 Claude 继续。确认 Prisma Client 已更新
npx prisma generate
npx prisma studioDraft 和 AiUsage 两张空表。看完按 Ctrl + C 关掉。审查 diff
对照上午第 3、5 节读代码，重点确认：文案 Action 里限额检查在 generateCopy 之前；保存用了 $transaction；草稿箱三个 Action 第一行都是 requireAdmin()；对话接口的限额检查在创建流之前。
验证保存和草稿箱
npm run dev，在文案助手生成一次，点“去草稿箱”。依次试：收藏、切到“收藏”筛选、编辑一条（标签输入 斯诺克, 周末日常 #绅士）、标记已发布、切到“已发布”筛选。
publishedAt 有了时间。验证次数上限
把 lib/ai/usage.ts 里的 DAILY_LIMIT 临时改成 1（你刚才已经用过至少一次），再生成一次。
30，用 git diff 确认。改提示词 v3，再测一轮
打开 docs/copy-eval.md，数一数每类问题出现几次，挑最多的那类，在 lib/ai/prompts.ts 里只改一处，并在 docs/prompt-log.md 记下改了什么、为什么。然后用同样的 5 个主题各生成一次，在评估表里新建“第 2 轮”，用同一把尺子打分。这次草稿会自动存进草稿箱，不用再手动复制。
可选：effort 对比实验
在 generate-copy.ts 的 output_config 里加上 effort: "medium"，再用 5 个主题跑一轮。用上午第 4 节的 SQL 对比两轮的 outputTokens，再对比分数。分数不降、token 明显减少，就保留这个设置，并记进 prompt-log.md。
先迁移正式数据库，再合并
按 DAY 54 你迁移正式数据库的方式，对正式库执行迁移（通常是在指向正式库的 DATABASE_URL 下运行 npx prisma migrate deploy）。然后提交并开 PR：
npm run typecheck
npm test
npm run build
git add .
git commit -m "feat: 草稿箱、用量记录和每日次数上限"
git push -u origin feat/drafts
gh pr create --fillmodel World 里加 drafts Draft[]；也可以先运行 npx prisma format，它会自动补上。npx prisma generate。Prisma 7 的 migrate dev 不会自动生成客户端。生成后如果还报错，在 VS Code 里按 Cmd + Shift + P，运行 TypeScript: Restart TS Server。ai_usage、drafts，列叫 created_at、input_tokens。如果 Claude 生成的 schema 漏了 @map，数据库里就会出现驼峰名字，审查时要让它补上再迁移。prisma migrate deploy，再重新部署。recordUsage（去 Prisma Studio 看 AiUsage 有没有新行）；确认限额检查写在调用 Claude 之前，而不是之后。改完提示词后平均分提高了吗？哪一处改动最有效？
用你两轮评估的真实数据回答。好的回答包括：两轮的平均分（比如小红书 3.6 到 4.0，TikTok 3.0 到 3.8）；你针对的问题在两轮中各出现几次（比如 TikTok 标题超长从 3 次降到 0 次）；有没有新出现的问题；以及你的判断，比如“加了一个 TikTok 标题的例子最有效，因为目标问题消失而且没有带来新问题”。如果平均分只差零点几分、问题次数也没变，诚实地写“这次改动效果不明显”，并说明下一步打算改哪里。
每日次数上限为什么要在调用 Claude 之前检查？如果放在之后会怎样？
限额的目的是在花钱之前拦住请求。放在之后检查，Claude 已经生成完了、钱已经花了，拦下来只是不显示结果，等于白花钱；如果代码出了死循环，限额根本挡不住费用增长。所以顺序必须是登录、校验、限额都通过之后，才调用 Claude。
草稿的发布状态为什么用 status 枚举加 publishedAt，而不是一个布尔值 published？
枚举以后可以扩展新状态（比如“已排期”），布尔值只能表示是或否，加状态就得改表结构；publishedAt 记录了发布的具体时间，复盘时可以和那段时间的点击数据对照，布尔值没有这个信息。改回未发布时把 publishedAt 清空，两者保持一致。
ClickEvent 和 QuizResult 两张统计表，说出每个字段和索引的用途。文案助手帮你写内容，但发出去之后效果怎样？你的链接页放在四个平台的简介里，访客点了哪个平台的按钮、测试小游戏测出哪个世界的人最多，这些数据能告诉你观众更喜欢哪一面的东哥。今天先把数据收集起来，明天做成看板。
在程序里记录“某件事发生了”，行话叫埋点。就像在店门口装一个计数器：有人进门就记一下。一条埋点记录通常回答三个问题：
同样重要的是不记录什么：不记录 IP 地址、不记录姓名和联系方式、不记录访客在别的网站做了什么。你只想知道趋势，不需要知道具体是谁。少收集数据，泄露时损失就小，也更尊重观众。
收集之前还要想清楚：这些数据能帮你回答什么问题？比如一个月下来 TikTok 按钮的点击一直最少，可能是 TikTok 的观众不爱跳出去，也可能是你在 TikTok 简介里根本没放链接页。数据本身不直接给答案，但它会告诉你该去追问什么。也要记住它的边界：“点了按钮”只说明有人想去看看，不等于关注，更不等于喜欢。
计数器最怕的是“一个人被记成很多次”。常见来源有：
我们用三招应对：
3f2a...），写进一个只有服务端能读的 cookie（DAY 46 学过 cookie）。之后这个浏览器的每次上报都带着同一个编号。要诚实地认识它的局限：清掉 cookie、换个浏览器，就会被当成新访客；一个不保存 cookie 的脚本，每次请求都会被当成新人。它挡得住“正常人的重复操作”和“守规矩的机器人”，挡不住有心人。对你自己看趋势来说，这已经够用；更严格的限流会在 DAY 67 安全加固时再做。
dongge-web/prisma/schema.prisma（追加，并修改 World）
enum SocialPlatform {
XIAOHONGSHU
TIKTOK
FACEBOOK
INSTAGRAM
@@map("social_platform")
}
model ClickEvent {
id Int @id @default(autoincrement())
platform SocialPlatform
visitorId String @map("visitor_id")
createdAt DateTime @default(now()) @map("created_at")
@@index([createdAt])
@@index([visitorId, platform, createdAt])
@@map("click_events")
}
model QuizResult {
id Int @id @default(autoincrement())
visitorId String @map("visitor_id")
createdAt DateTime @default(now()) @map("created_at")
worldId Int @map("world_id")
world World @relation(fields: [worldId], references: [id])
@@index([createdAt])
@@index([visitorId, createdAt])
@@map("quiz_results")
}
// 在已有的 model World { ... } 里再加一行：
// quizResults QuizResult[]设计思路：
SocialPlatform 是新的枚举，四个平台都在里面。它和昨天的 DraftPlatform 分开，因为草稿只有两个平台，意思不同，不要混用。QuizResult 用外键指向 World，和 Look、Draft 一样。表名、列名照 DAY 42 的规矩用 @@map、@map 翻译成小写加下划线：数据库里是 click_events、quiz_results、visitor_id、created_at，下面写 SQL 时用的就是这些名字。createdAt 给按时间汇总用；[visitorId, platform, createdAt] 给去重查询用，去重时要查“这个访客在这个平台最近一次点击是什么时候”，这个组合索引正好对上。你可能注意到 visitorId 只是一个字符串，没有指向某张“访客表”。因为我们对访客一无所知，也不想知道，建一张只有编号的表没有意义。它唯一的作用是让同一个浏览器的多条记录能被认出来是“同一个人”。
先把“规则”写成纯函数，不碰数据库和 cookie，DAY 63 可以直接测试：
dongge-web/lib/track/rules.ts
export const CLICK_WINDOW_MINUTES = 30;
export const QUIZ_WINDOW_MINUTES = 10;
const BOT_PATTERN = /bot|crawler|spider|preview|facebookexternalhit|curl|wget|python-requests/i;
// 没有 User-Agent，或者自我介绍像机器人，就不计数
export function looksLikeBot(userAgent: string | null) {
if (!userAgent) return true;
return BOT_PATTERN.test(userAgent);
}
// 上一次记录距离现在不到 windowMinutes 分钟，就算重复
export function isDuplicate(last: Date | null, now: Date, windowMinutes: number) {
if (!last) return false;
return now.getTime() - last.getTime() < windowMinutes * 60 * 1000;
}BOT_PATTERN 是一个正则表达式（一种描述文字规律的写法，DAY 59 的 splitTags 里也用过），竖线表示“或”，末尾的 i 表示不区分大小写。注意我们把 curl 也算作机器人，所以你用 curl 测试时不会产生记录，这正好可以用来验证过滤是否生效。isDuplicate 用毫秒相减判断间隔，getTime() 返回从 1970 年起的毫秒数。
dongge-web/lib/track/visitor.ts
import "server-only";
import { cookies } from "next/headers";
const COOKIE_NAME = "dg_vid";
const ONE_YEAR = 60 * 60 * 24 * 365;
// 读取匿名访客编号；没有就生成一个随机编号写进 cookie
export async function getOrCreateVisitorId() {
const store = await cookies();
const existing = store.get(COOKIE_NAME)?.value;
if (existing && existing.length <= 64) return existing;
const id = crypto.randomUUID();
store.set(COOKIE_NAME, id, {
httpOnly: true,
sameSite: "lax",
secure: process.env.NODE_ENV === "production",
maxAge: ONE_YEAR,
path: "/",
});
return id;
}crypto.randomUUID() 生成一个几乎不可能重复的随机编号，它和访客的任何真实信息都无关。httpOnly 让页面上的 JavaScript 读不到这个 cookie；secure 让它在线上只通过 HTTPS 发送；maxAge 一年后过期。existing.length <= 64 是一个小保护，防止有人塞进一个超长的假编号。Next.js 允许在 Route Handler 里用 cookies().set() 写 cookie。
dongge-web/app/api/track/click/route.ts
import { z } from "zod";
import { prisma } from "@/lib/prisma";
import { getOrCreateVisitorId } from "@/lib/track/visitor";
import { CLICK_WINDOW_MINUTES, isDuplicate, looksLikeBot } from "@/lib/track/rules";
// 前端传来的是 lib/data 里的平台 id，这里翻译成数据库的枚举值
const PLATFORMS = {
xiaohongshu: "XIAOHONGSHU",
tiktok: "TIKTOK",
facebook: "FACEBOOK",
instagram: "INSTAGRAM",
} as const;
const ClickInput = z.object({
platform: z.enum(["xiaohongshu", "tiktok", "facebook", "instagram"]),
});
export async function POST(request: Request) {
if (looksLikeBot(request.headers.get("user-agent"))) {
return new Response(null, { status: 204 });
}
const parsed = ClickInput.safeParse(await request.json().catch(() => null));
if (!parsed.success) {
return new Response(null, { status: 400 });
}
const visitorId = await getOrCreateVisitorId();
const platform = PLATFORMS[parsed.data.platform];
const last = await prisma.clickEvent.findFirst({
where: { visitorId, platform },
orderBy: { createdAt: "desc" },
select: { createdAt: true },
});
if (!isDuplicate(last?.createdAt ?? null, new Date(), CLICK_WINDOW_MINUTES)) {
await prisma.clickEvent.create({ data: { visitorId, platform } });
}
return new Response(null, { status: 204 });
}这是你第一个不需要登录的写入接口，因为点按钮的是访客。所以它的保护全靠自身：Zod 只接受四个固定的平台 id，再用 PLATFORMS 翻译成数据库的枚举值；机器人直接忽略；重复的不写入；返回 204（成功，但没有内容），不透露任何信息。注意机器人和重复请求也返回 204 而不是报错，这样刷量的人得不到“被拦住了”的反馈。
两个小细节值得留意。第一，机器人判断放在最前面，因为它只看请求头，最便宜；能早点拒绝的就不要先去解析请求体、查数据库。第二，“先查最近一条、再决定写不写”这两步之间有一个很短的空隙，如果同一个人在同一瞬间发来两个请求，两个请求可能都查到“没有记录”，于是都写入了。这种情况很少见，对趋势统计几乎没有影响，所以我们接受它。你在审查时能指出这样的问题并说明为什么可以接受，就已经在像工程师一样思考了。
dongge-web/app/api/track/quiz/route.ts
import { z } from "zod";
import { prisma } from "@/lib/prisma";
import { getOrCreateVisitorId } from "@/lib/track/visitor";
import { QUIZ_WINDOW_MINUTES, isDuplicate, looksLikeBot } from "@/lib/track/rules";
const QuizInput = z.object({
world: z.enum(["gentleman", "street", "thai"]),
});
export async function POST(request: Request) {
if (looksLikeBot(request.headers.get("user-agent"))) {
return new Response(null, { status: 204 });
}
const parsed = QuizInput.safeParse(await request.json().catch(() => null));
if (!parsed.success) {
return new Response(null, { status: 400 });
}
const visitorId = await getOrCreateVisitorId();
const last = await prisma.quizResult.findFirst({
where: { visitorId },
orderBy: { createdAt: "desc" },
select: { createdAt: true },
});
if (!isDuplicate(last?.createdAt ?? null, new Date(), QUIZ_WINDOW_MINUTES)) {
const world = await prisma.world.findUnique({
where: { slug: parsed.data.world },
select: { id: true },
});
if (world) {
await prisma.quizResult.create({ data: { visitorId, worldId: world.id } });
}
}
return new Response(null, { status: 204 });
}结构和点击接口几乎一样，区别是去重不分世界：同一个人 10 分钟内重做测试，只记第一次的结果。
上报有一条原则：统计失败不能影响访客。访客点小红书按钮，是想去你的小红书主页，不是来帮你统计的。所以上报请求发出去就不管了，失败也不提示。
dongge-web/components/TrackLink.tsx
"use client";
type Props = {
platform: string; // 平台 id，和 lib/data 里的一致，比如 "xiaohongshu"
href: string;
className?: string;
style?: React.CSSProperties;
children: React.ReactNode;
};
export default function TrackLink({ platform, href, className, style, children }: Props) {
function handleClick() {
fetch("/api/track/click", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ platform }),
keepalive: true,
}).catch(() => {});
}
return (
<a
href={href}
target="_blank"
rel="noopener noreferrer"
onClick={handleClick}
className={className}
style={style}
>
{children}
</a>
);
}几处细节：链接在新标签页打开（target="_blank"），原页面不会被关掉，请求能正常完成；keepalive: true 是额外的保险，即使页面随后被关闭，浏览器也会尽量把这个请求发完；.catch(() => {}) 吞掉错误，访客什么都感觉不到。浏览器还有一个专门的 navigator.sendBeacon 用于这种场景，我们用 fetch 加 keepalive，是因为它的请求和响应处理（包括写 cookie）和你熟悉的 fetch 完全一样。文件名用大写开头，和 components 里已有的 PlatformButton.tsx 保持一致。
为什么这里用 Route Handler 加 fetch，而不是 DAY 43 学的 Server Action？Server Action 适合“提交表单然后更新页面”；而上报是“发出去就不管、不需要任何返回、任何页面都可能调用”的事情，一个普通的 POST 接口更直接，也方便以后从别的地方（比如测试小游戏）调用。
接下来改 DAY 32 写的 PlatformButton：多接收一个平台 id，把里面的 <a> 换成 TrackLink。
dongge-web/components/PlatformButton.tsx
import TrackLink from "@/components/TrackLink";
type PlatformButtonProps = {
id: string;
name: string;
url: string;
color?: string;
};
export default function PlatformButton({ id, name, url, color = "#1f2a2e" }: PlatformButtonProps) {
return (
<TrackLink
platform={id}
href={url}
style={{ borderColor: color }}
className="block rounded-xl border-2 bg-card px-6 py-3.5 text-center font-semibold transition hover:-translate-y-0.5"
>
{name}
</TrackLink>
);
}DAY 39 说过“能点不等于需要客户端组件，要看你有没有自己写事件处理”。现在我们要写 onClick 了，但只有最里面的 TrackLink 需要变成客户端组件，PlatformButton 本身仍然是服务端组件。app/links/page.tsx 里渲染按钮的地方，把 id 也传进去：<PlatformButton key={platform.id} id={platform.id} name={platform.name} url={platform.url} />。平台 id 就是 DAY 28 数据里的 xiaohongshu、tiktok 这些，接口会把它们翻译成数据库里的枚举值。示例链接记得换成你自己的主页链接。
测试小游戏在 components/Quiz.tsx 里用 scoreQuiz 算出结果（类型是 DAY 39 的 World）。在这个组件里加一个 useEffect，把下面的 result 换成你保存结果的那个 state：
// result：scoreQuiz 算出的世界，还没做完时是 null
useEffect(() => {
if (!result) return;
fetch("/api/track/quiz", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ world: result }), // "gentleman" | "street" | "thai"
keepalive: true,
}).catch(() => {});
}, [result]);DAY 30 学过，依赖数组里写了 result，结果出来时执行一次；还没出结果时直接 return，什么都不发。开发环境下 React 的严格模式会故意把 effect 执行两次来帮你发现问题，所以本地会发出两次请求。这时去重规则正好派上用场：第二次在 10 分钟窗口内，不会写入。上线后只会执行一次。
数据有了，怎么看每天各平台点了多少次？用 DAY 40 学过的 GROUP BY，再加一个新函数 date_trunc，它把时间“截断”到天、周或月：date_trunc('day', 某个时间) 会把 15:42 变成当天的 00:00。
但有一个坑：Prisma 存进 PostgreSQL 的时间是 UTC 时间（世界标准时间），而且存成了“不带时区”的类型。如果你在 UTC+8 的地方，晚上 7 点的点击在数据库里记的是当天上午 11 点，而早上 7 点的点击记的是前一天晚上 11 点。直接按天截断，就会把一部分数据算到前一天。正确的写法是先告诉数据库“这是 UTC 时间”，再换算成你的时区：
SELECT date_trunc('day', (created_at AT TIME ZONE 'UTC') AT TIME ZONE 'Asia/Shanghai')::date AS day,
platform,
count(*) AS clicks
FROM click_events
GROUP BY 1, 2
ORDER BY 1 DESC, 2;逐段读：created_at AT TIME ZONE 'UTC' 把不带时区的时间解释为 UTC；再 AT TIME ZONE 'Asia/Shanghai' 换算成 UTC+8 的当地时间，把 Asia/Shanghai 换成你所在的时区名，比如 Asia/Bangkok 或 Asia/Singapore；date_trunc('day', ...) 截到当天零点；::date 只保留日期；GROUP BY 1, 2 表示按第 1 列和第 2 列分组，省得把长长的表达式再写一遍。注意 SQL 里写的是数据库里的名字 click_events、created_at，不是代码里的 ClickEvent、createdAt。
测试结果按天、按世界汇总，需要用 DAY 41 学过的 JOIN 把世界的名字查出来：
SELECT date_trunc('day', (q.created_at AT TIME ZONE 'UTC') AT TIME ZONE 'Asia/Shanghai')::date AS day,
w.name AS world,
count(*) AS results
FROM quiz_results q
JOIN worlds w ON w.id = q.world_id
GROUP BY 1, 2
ORDER BY 1 DESC, 2;q 和 w 是表的简称（别名），写在 FROM quiz_results q 后面，之后用 q.created_at 就表示“quiz_results 表的 created_at 列”。两张表都有 id、created_at 这样的同名列时，别名能避免混淆。防刷功能的验收，本质上是你亲自去刷，看它是否按预期拦住，再看它是否误伤正常访客。把每个场景写成“操作、预期的数据库变化”：
ClickEvent 只多 1 行。visitorId 不一样（新访客）。数据库的变化用 Prisma Studio 或 Neon 的 SQL 编辑器确认，不要只看接口返回了 204，因为我们故意让所有情况都返回 204。这也是审查今天代码的关键：接口“看起来都成功”，真正的差别在数据库里。明天我们把这些数据做成按周汇总的看板。
开分支，写需求卡
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/trackingdongge-web/docs/specs/day60-tracking.md
# 需求：平台点击统计和测试结果统计
## 背景
想知道访客点了哪个平台、测试测出哪个世界，为明天的看板准备数据。
## 要做
- schema：SocialPlatform 枚举，ClickEvent、QuizResult 模型（见上午第 3 节，按 DAY 42 规矩用 @map、@@map），World 加 quizResults。
迁移名 add-tracking。
- lib/track/rules.ts：looksLikeBot、isDuplicate（纯函数）和两个窗口常量（30 分钟、10 分钟）。
- lib/track/visitor.ts：getOrCreateVisitorId，httpOnly cookie dg_vid，有效期一年。
- POST /api/track/click 和 /api/track/quiz：不需要登录；机器人忽略；Zod 校验；按窗口去重；一律返回 204，校验失败返回 400。
- components/TrackLink.tsx：客户端组件，点击时 fetch 上报平台 id（keepalive），失败不提示。
- components/PlatformButton.tsx 增加 id 参数，内部改用 TrackLink；app/links/page.tsx 传入 platform.id。
- 接口接收小写平台 id（xiaohongshu 等），翻译成 SocialPlatform 枚举值再写库。
- components/Quiz.tsx 出结果后用 useEffect 上报结果。
## 不做
- 不记录 IP、不记录任何个人信息。不做看板（明天做）。不做限流（DAY 67）。
## 验收标准
- [ ] 连点小红书按钮 10 次，ClickEvent 只多 1 行；再点 TikTok 多 1 行。
- [ ] 无痕窗口点小红书，多 1 行且 visitorId 不同。
- [ ] curl 调用 /api/track/click，数据库不多行。
- [ ] 平台 id 传 "weibo" 返回 400。
- [ ] 做一遍测试小游戏，QuizResult 多 1 行，世界正确；10 分钟内重做不再增加。
- [ ] 点平台按钮后能正常在新标签页打开平台主页，没有卡顿。
- [ ] migration.sql 里没有 DROP。
## 约束
遵守 CLAUDE.md。Plan、迁移、审查
把「问 Claude」第一条发给 Claude。生成迁移后，照昨天的方法读 migration.sql，确认只有新建。然后：
npx prisma generate
git diff --stat审查重点：两个接口有没有要求登录（不应该要求）；机器人判断是否在最前面；去重是否查的是“同访客同平台的最近一条”；前端上报失败时是否静默。
验证点击去重
npm run dev，另开一个终端运行 npx prisma studio。打开你的链接页，快速连点小红书按钮 10 次（会打开很多标签页，关掉即可），再点一次 TikTok。在 Prisma Studio 里刷新 ClickEvent。
ClickEvent 只有 2 行，一行 XIAOHONGSHU，一行 TIKTOK，visitorId 相同。验证新访客和 cookie
打开开发者工具的 Application 面板，在 Cookies 里找到 dg_vid，确认 HttpOnly 一栏打了勾。然后用 Cmd + Shift + N 开一个无痕窗口，打开链接页点小红书。
ClickEvent 多了 1 行，visitorId 和之前的不同。验证机器人过滤和输入校验
curl -i -X POST http://localhost:3000/api/track/click \
-H "Content-Type: application/json" \
-d '{"platform":"xiaohongshu"}'
curl -i -X POST http://localhost:3000/api/track/click \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0" \
-d '{"platform":"weibo"}'204，但数据库没有新行（curl 被当成机器人）；第二条假装成浏览器，因为平台 id 不合法返回 400。验证测试结果上报
打开测试小游戏，完整做一遍。看 Prisma Studio 的 QuizResult。然后马上再做一遍。
worldId 对应你测出的世界（开发环境下即使 effect 执行了两次，也只有 1 行）；第二遍不再增加。在 Neon 里跑按天汇总
打开 Neon 控制台的 SQL Editor（选开发用的数据库分支），把上午第 6 节的两条 SQL 粘进去运行，时区换成你所在的时区。
记下你的时区决定
在 CLAUDE.md 末尾加一个小节，让以后的代码都用同一个时区：
## 统计约定
- 数据库时间一律是 UTC。按天、按周汇总时换算到 Asia/Shanghai（按你的实际时区修改）。
- 统计接口不记录 IP 和任何个人信息，只用匿名 cookie dg_vid 区分访客。迁移正式库，提交合并
按 DAY 54 的方式对正式数据库执行迁移，然后：
npm run typecheck
npm test
npm run build
git add .
git commit -m "feat: 平台点击和测试结果统计，简单防刷"
git push -u origin feat/tracking
gh pr create --fillClickEvent 多了一行。click 请求的状态码。如果因为页面跳走看不到，勾选 Network 面板的 Preserve log。返回 204 却没新行，可能是 30 分钟窗口内的重复点击，换一个平台或开无痕窗口再试。AT TIME ZONE 'UTC' 那一步，或者时区名写错。时区名要用 Asia/Shanghai 这种“地区/城市”格式。click_events、created_at。如果数据库里真的出现了驼峰名字的表，说明 schema 漏了 @@map、@map，让 Claude 补上再做一次迁移。npx prisma generate，或者 TypeScript 服务需要重启。一个人连点 100 次按钮，你的统计会变成什么样？
100 次请求都会到达接口，但只有第一次会写入数据库：同一个浏览器带着同一个匿名编号，同一个平台在 30 分钟内的后续点击都被判为重复，统计只加 1。如果他 30 分钟后再点，会再加 1。如果他点一次清一次 cookie，或者用不保存 cookie 的脚本，每次都会被当成新访客，统计会被刷高，这是目前方案挡不住的，DAY 67 会加限流。
为什么不记录访客的 IP？匿名编号能做到什么、做不到什么？
IP 属于可能识别个人的信息，而你只需要看趋势，用不上它；少收集就少一份泄露风险，也更尊重观众。匿名编号能区分“是不是同一个浏览器”，足够做去重和统计独立访客；它做不到识别同一个人的不同设备，清掉 cookie 或换浏览器就会变成新编号，也挡不住刻意伪造的脚本。
数据库里存的是 UTC 时间，按你所在的时区按天汇总，SQL 要怎么写？为什么不能直接对 createdAt 做 date_trunc？
写成 date_trunc('day', (created_at AT TIME ZONE 'UTC') AT TIME ZONE '你的时区')。直接截断是按 UTC 的零点切分“一天”，而你所在时区的一天和 UTC 的一天错开了几个小时，靠近零点的数据会被算到相邻的日期。先声明它是 UTC，再换算到当地时间，切出来的“一天”才是你理解的那一天。
$queryRaw 安全地执行。昨天我们开始收集点击和测试结果。今天把它们做成后台的看板。动手之前先问：我打开看板，想回答什么问题？图表是回答问题的工具，不是装饰。对你来说，每周最关心的大概是三个问题：
再加一张数据表格放在图表下面：图表看趋势，表格看精确数字，也方便你核对图表有没有画错。
还有一条规矩：同一个平台在看板上始终用同一种颜色，并且一定配图例。颜色只是辅助，文字标签才是主角，这样色弱的朋友或者黑白打印时也能看懂。
最后想一想“谁看、多久看一次”。这个看板只有你一个人看，大概每周一看一次。所以它不需要实时刷新，不需要十几个图表，也不需要复杂的筛选。一个人每周花两分钟就能看完、看完知道下一步做什么，才是好看板。以后想加图表时，先问自己：这张图会改变我的哪个决定？答不上来，就先不加。
昨天学了按天汇总，按周只要把 date_trunc('day', ...) 换成 date_trunc('week', ...)。PostgreSQL 的“周”从周一开始，截断后得到那一周周一的零点。时区的处理和昨天完全一样。
举个例子：一次点击发生在 UTC+8 的 9 月 24 日（周四）晚上 9 点，数据库里存的是 UTC 的 9 月 24 日下午 1 点。先换算回当地时间，再按周截断，得到 9 月 21 日（周一）零点，于是它被算进“9 月 21 日这一周”。如果忘了换算时区，大部分时候结果碰巧一样，但周一早上 8 点前的点击会被算到上一周，这种错误平时很难发现。
SELECT to_char(date_trunc('week', (created_at AT TIME ZONE 'UTC') AT TIME ZONE 'Asia/Shanghai'), 'YYYY-MM-DD') AS week,
platform::text AS platform,
count(*)::int AS clicks
FROM click_events
WHERE created_at >= now() - interval '56 days'
GROUP BY 1, 2
ORDER BY 1;比昨天多了三处：
to_char(..., 'YYYY-MM-DD')：把时间转成 2026-09-21 这样的文字。为什么不直接返回日期类型？因为日期传到 JavaScript 里会变成 Date 对象，又会被本机时区影响，一不小心就差一天。直接要文字最省心。platform::text：platform 是枚举类型，转成普通文字，JavaScript 那边处理起来简单。count(*)::int：PostgreSQL 的 count 返回的是 64 位大整数，传到 JavaScript 会变成 BigInt 类型。BigInt 不能直接交给客户端组件，Next.js 会报“无法序列化 BigInt”的错。转成 int 就变成普通数字了。WHERE 只取最近 56 天（8 周）的数据。第一周可能只包含其中几天，看的时候心里有数即可。
Prisma 的 findMany、groupBy 没法按周截断时间，这种时候用 $queryRaw 直接写 SQL。它用的是“带标签的模板字符串”：
dongge-web/lib/stats/queries.ts
import "server-only";
import { prisma } from "@/lib/prisma";
// 换成你所在的时区，和 CLAUDE.md 的统计约定保持一致
export const REPORT_TZ = "Asia/Shanghai";
const WEEKS = 8;
const DAY = 24 * 60 * 60 * 1000;
export type ClickRow = { week: string; platform: string; clicks: number };
export type QuizRow = { week: string; world: string; total: number };
function since() {
return new Date(Date.now() - WEEKS * 7 * DAY);
}
export async function weeklyClicks() {
return prisma.$queryRaw<ClickRow[]>`
SELECT to_char(date_trunc('week', (created_at AT TIME ZONE 'UTC') AT TIME ZONE ${REPORT_TZ}::text), 'YYYY-MM-DD') AS week,
platform::text AS platform,
count(*)::int AS clicks
FROM click_events
WHERE created_at >= ${since()}
GROUP BY 1, 2
ORDER BY 1
`;
}
export async function weeklyQuizResults() {
return prisma.$queryRaw<QuizRow[]>`
SELECT to_char(date_trunc('week', (q.created_at AT TIME ZONE 'UTC') AT TIME ZONE ${REPORT_TZ}::text), 'YYYY-MM-DD') AS week,
w.slug AS world,
count(*)::int AS total
FROM quiz_results q
JOIN worlds w ON w.id = q.world_id
WHERE q.created_at >= ${since()}
GROUP BY 1, 2
ORDER BY 1
`;
}
// 最近 7 天和再往前 7 天的点击数，用滚动窗口，不受“今天星期几”影响
export async function clicksLast7Days() {
const now = Date.now();
const [recent, previous] = await Promise.all([
prisma.clickEvent.count({ where: { createdAt: { gte: new Date(now - 7 * DAY) } } }),
prisma.clickEvent.count({
where: { createdAt: { gte: new Date(now - 14 * DAY), lt: new Date(now - 7 * DAY) } },
}),
]);
return { recent, previous };
}逐段解释：
$queryRaw<ClickRow[]>`...`：尖括号里告诉 TypeScript 每一行长什么样。注意这只是“你承诺的类型”，Prisma 不会检查，所以 SQL 里的列名（AS week 等）必须和类型对上。${REPORT_TZ} 和 ${since()}：看起来像字符串拼接，其实不是。Prisma 会把它们变成参数单独发给数据库，数据库把它们当作纯数据，绝不会当成 SQL 执行。这正是 DAY 45 讲的防 SQL 注入的方法。千万不要改用 $queryRawUnsafe 自己拼字符串。::text：告诉数据库这个参数是一段文字（时区名）。GROUP BY 1, 2：按第 1、2 列分组。这里不能把那个长表达式再写一遍，因为每个 ${...} 都会变成一个新参数，数据库会认为两处表达式“不一样”而报错。click_events、created_at、worlds），不是代码里的 ClickEvent、createdAt。这是 $queryRaw 和 findMany 最大的区别：findMany 会替你翻译名字，原生 SQL 不会。clicksLast7Days：关键数字用“最近 7 天对比再往前 7 天”，而不是“本周对比上周”。因为周三打开看板时，“本周”只有三天，和上周的七天比，永远显得在下跌。滚动窗口没有这个问题。SQL 返回的是“一周一个平台一行”的长表：
[
{ "week": "2026-09-14", "platform": "XIAOHONGSHU", "clicks": 12 },
{ "week": "2026-09-14", "platform": "TIKTOK", "clicks": 5 },
{ "week": "2026-09-21", "platform": "XIAOHONGSHU", "clicks": 9 }
]Recharts 要的是“一周一行、每个平台一列”的宽表：
[
{ "week": "9/14", "XIAOHONGSHU": 12, "TIKTOK": 5, "FACEBOOK": 0, "INSTAGRAM": 0 },
{ "week": "9/21", "XIAOHONGSHU": 9, "TIKTOK": 0, "FACEBOOK": 0, "INSTAGRAM": 0 }
]这个“长变宽”的转换叫透视（pivot）。SQL 也能做透视，但写法又长又难读；在 TypeScript 里做，逻辑清楚，还能写成纯函数，DAY 63 直接给它写测试。分工的原则是：数据库负责“筛选和计数”，这是它最擅长的；TypeScript 负责“整理成页面要的样子”。
dongge-web/lib/stats/shape.ts
export const PLATFORM_KEYS = ["XIAOHONGSHU", "TIKTOK", "FACEBOOK", "INSTAGRAM"] as const;
export type PlatformKey = (typeof PLATFORM_KEYS)[number];
export const WORLD_KEYS = ["gentleman", "street", "thai"] as const;
export type WorldKey = (typeof WORLD_KEYS)[number];
export type WeekClicks = { week: string } & Record<PlatformKey, number>;
export type WeekShare = { week: string; total: number } & Record<WorldKey, number>;
// "2026-09-21" 变成 "9/21"
export function weekLabel(isoDate: string) {
const [, month, day] = isoDate.split("-");
return `${Number(month)}/${Number(day)}`;
}
function isPlatform(value: string): value is PlatformKey {
return (PLATFORM_KEYS as readonly string[]).includes(value);
}
function isWorld(value: string): value is WorldKey {
return (WORLD_KEYS as readonly string[]).includes(value);
}
export function pivotClicks(rows: { week: string; platform: string; clicks: number }[]): WeekClicks[] {
const byWeek = new Map<string, WeekClicks>();
for (const row of rows) {
let item = byWeek.get(row.week);
if (!item) {
item = { week: weekLabel(row.week), XIAOHONGSHU: 0, TIKTOK: 0, FACEBOOK: 0, INSTAGRAM: 0 };
byWeek.set(row.week, item);
}
if (isPlatform(row.platform)) {
item[row.platform] += row.clicks;
}
}
return [...byWeek.values()];
}
export function toShares(rows: { week: string; world: string; total: number }[]): WeekShare[] {
const byWeek = new Map<string, WeekShare>();
for (const row of rows) {
let item = byWeek.get(row.week);
if (!item) {
item = { week: weekLabel(row.week), total: 0, gentleman: 0, street: 0, thai: 0 };
byWeek.set(row.week, item);
}
if (isWorld(row.world)) {
item[row.world] += row.total;
item.total += row.total;
}
}
// 次数换算成百分比，四舍五入到整数
return [...byWeek.values()].map((w) => {
const pct = (n: number) => (w.total === 0 ? 0 : Math.round((n / w.total) * 100));
return { ...w, gentleman: pct(w.gentleman), street: pct(w.street), thai: pct(w.thai) };
});
}要点：
(typeof PLATFORM_KEYS)[number]：从数组里取出所有元素组成联合类型，等于 "XIAOHONGSHU" | "TIKTOK" | ...。以后加平台只改数组一处。Record<PlatformKey, number>：一个对象，四个平台名都是键，值都是数字。Map：一个“按周查找”的小字典。SQL 已经按周排好序，Map 会记住放入的顺序，所以结果也是按周排好的。value is PlatformKey：这种写法叫“类型守卫”：函数返回真时，TypeScript 就知道这个字符串是四个平台名之一，才允许用它当键。数据库里万一出现陌生的值，会被安全地跳过。Recharts 是基于 React 的图表库：你用组件“搭”出一张图，而不是自己画线条。它的官网已经搬到 recharts.github.io，写代码前请先看一遍官方的入门页，确认当前版本的写法。安装：
npm install recharts一张柱状图由这些组件组成：BarChart 是画布，接收 data；XAxis 和 YAxis 是坐标轴，dataKey="week" 表示横轴用每行的 week 字段；Bar 是一组柱子，dataKey="TIKTOK" 表示高度取每行的 TIKTOK 字段；Tooltip 是鼠标悬停时的提示框；Legend 是图例；CartesianGrid 是背景网格线。
Recharts 要测量页面宽度、响应鼠标悬停，这些都只能在浏览器里做，所以图表组件必须是客户端组件，第一行写 "use client"。数据在服务端查好，通过 props 传进来（DAY 39 的模式）。
为什么数据要在服务端查、再传给客户端组件，而不是让图表组件自己去查？一是安全：查数据库需要 DATABASE_URL，它绝不能出现在浏览器里；二是简单：服务端组件可以直接 await 数据库查询，客户端组件则要额外写一个接口再 fetch。所以分工是：服务端负责“拿数据”，客户端负责“画出来、响应鼠标”。
为什么用柱状图而不是折线图？折线图适合很多个时间点的连续趋势，比如 90 天每天的数据；我们只有 8 周、每周 4 个平台，柱子能让你直接比较“同一周里谁高谁低”。等你积累了半年数据，想看长期走势时，可以再加一张折线图。
尺寸方面，官方文档介绍了 3.3 版本起的 responsive 属性：加上它，图表会跟随外层容器的宽度变化，再用 style 设置宽度和宽高比。更早的版本用 ResponsiveContainer 包一层，效果类似。
dongge-web/components/admin/WeeklyClicksChart.tsx
"use client";
import { Bar, BarChart, CartesianGrid, Legend, Tooltip, XAxis, YAxis } from "recharts";
import type { WeekClicks } from "@/lib/stats/shape";
// 每个平台固定一种颜色，整个看板保持一致
const SERIES = [
{ key: "XIAOHONGSHU", name: "小红书", color: "#2a78d6" },
{ key: "TIKTOK", name: "TikTok", color: "#eb6834" },
{ key: "FACEBOOK", name: "Facebook", color: "#1baf7a" },
{ key: "INSTAGRAM", name: "Instagram", color: "#eda100" },
] as const;
export default function WeeklyClicksChart({ data }: { data: WeekClicks[] }) {
if (data.length === 0) {
return <p className="text-gray-500">这段时间还没有点击数据。</p>;
}
return (
<BarChart data={data} responsive style={{ width: "100%", maxWidth: 720, aspectRatio: 1.8 }}>
<CartesianGrid strokeDasharray="3 3" vertical={false} />
<XAxis dataKey="week" />
<YAxis allowDecimals={false} width={32} />
<Tooltip />
<Legend />
{SERIES.map((s) => (
<Bar key={s.key} dataKey={s.key} name={s.name} fill={s.color} radius={[4, 4, 0, 0]} />
))}
</BarChart>
);
}说明：name 是图例和提示框里显示的中文名；fill 是颜色；radius 让柱子顶端有 4 像素圆角；allowDecimals={false} 让纵轴只显示整数，点击数不可能是 2.5 次；vertical={false} 去掉竖向网格线，画面更干净。颜色取自一套经过色弱检查的配色，四个颜色相邻时也容易区分。
dongge-web/components/admin/WorldShareChart.tsx
"use client";
import { Bar, BarChart, CartesianGrid, Legend, Tooltip, XAxis, YAxis } from "recharts";
import type { WeekShare } from "@/lib/stats/shape";
// 世界用另一组颜色，避免和平台的颜色混淆
const SERIES = [
{ key: "gentleman", name: "绅士", color: "#e87ba4" },
{ key: "street", name: "街头", color: "#008300" },
{ key: "thai", name: "泰风", color: "#4a3aa7" },
] as const;
export default function WorldShareChart({ data }: { data: WeekShare[] }) {
if (data.length === 0) {
return <p className="text-gray-500">这段时间还没有测试结果。</p>;
}
return (
<BarChart data={data} responsive style={{ width: "100%", maxWidth: 720, aspectRatio: 1.8 }}>
<CartesianGrid strokeDasharray="3 3" vertical={false} />
<XAxis dataKey="week" />
<YAxis domain={[0, 100]} unit="%" width={44} />
<Tooltip formatter={(value) => `${value}%`} />
<Legend />
{SERIES.map((s) => (
<Bar key={s.key} dataKey={s.key} name={s.name} stackId="world" fill={s.color} stroke="#ffffff" strokeWidth={2} />
))}
</BarChart>
);
}和上一张图的区别：三个 Bar 都写了同一个 stackId="world"，它们就会叠成一根柱子；纵轴 domain={[0, 100]} 固定在 0 到 100，unit="%" 给刻度加上百分号；Tooltip 的 formatter 让提示框里也显示百分号；白色的 stroke 在相邻两段之间留一条细缝，分界更清楚。
dongge-web/app/admin/dashboard/page.tsx
import { requireAdmin } from "@/lib/admin";
import { clicksLast7Days, weeklyClicks, weeklyQuizResults } from "@/lib/stats/queries";
import { PLATFORM_KEYS, pivotClicks, toShares } from "@/lib/stats/shape";
import WeeklyClicksChart from "@/components/admin/WeeklyClicksChart";
import WorldShareChart from "@/components/admin/WorldShareChart";
const PLATFORM_NAMES = {
XIAOHONGSHU: "小红书",
TIKTOK: "TikTok",
FACEBOOK: "Facebook",
INSTAGRAM: "Instagram",
} as const;
export default async function DashboardPage() {
await requireAdmin();
const [clickRows, quizRows, last7] = await Promise.all([
weeklyClicks(),
weeklyQuizResults(),
clicksLast7Days(),
]);
const clicks = pivotClicks(clickRows);
const shares = toShares(quizRows);
return (
<div className="mx-auto max-w-4xl space-y-10 p-6">
<h1 className="text-2xl font-bold">数据看板</h1>
<section>
<p className="text-sm text-gray-500">最近 7 天平台按钮点击</p>
<p className="text-4xl font-bold">{last7.recent}</p>
<p className="text-sm text-gray-500">再往前 7 天：{last7.previous}</p>
</section>
<section className="space-y-3">
<h2 className="text-lg font-bold">每周各平台点击数</h2>
<WeeklyClicksChart data={clicks} />
<table className="w-full text-sm">
<thead>
<tr>
<th className="text-left">周（周一开始）</th>
{PLATFORM_KEYS.map((k) => (
<th key={k} className="text-right">{PLATFORM_NAMES[k]}</th>
))}
</tr>
</thead>
<tbody>
{clicks.map((w) => (
<tr key={w.week}>
<td>{w.week}</td>
{PLATFORM_KEYS.map((k) => (
<td key={k} className="text-right">{w[k]}</td>
))}
</tr>
))}
</tbody>
</table>
</section>
<section className="space-y-3">
<h2 className="text-lg font-bold">测试结果中各世界的占比</h2>
<WorldShareChart data={shares} />
<p className="text-sm text-gray-500">
每周测试人数：{shares.map((w) => `${w.week} 共 ${w.total} 人`).join("，")}
</p>
</section>
</div>
);
}页面是服务端组件：第一行照 DAY 47 的约定调用 requireAdmin()，再用 Promise.all 同时发出三个查询（DAY 22 学过，并行比一个一个等更快），整理好数据后交给两个客户端图表组件。百分比图下面写上每周的测试人数，因为“占比 60%”在 5 个人和 500 个人时意义完全不同。
为什么每个后台页面都要自己检查，而不是在后台布局里查一次？DAY 47 讲过：布局在页面之间切换时不会重新执行，靠它挡人并不可靠；这个页面会直接查数据库，检查就要放在离数据最近的地方。表格用的是和图表同一份 clicks 数据，保证两边的数字一定一致。
看板最怕的不是难看，而是数字错了你却不知道。验收时至少做两件事：
你还可能发现，看板上的小红书点击数和小红书后台显示的“主页访问”对不上。这很正常：你的看板只统计“在链接页点了小红书按钮”的次数，小红书后台统计的是所有来源的访问。两个数字回答的是不同的问题，不需要一致，但你要清楚每个数字到底在数什么。
审查 Claude 的代码时，重点看三处：SQL 里有没有 ::int；$queryRaw 里是不是用 ${...} 传参数，而不是拼字符串；图表组件有没有 "use client"。明天把文案助手、草稿箱和看板合成一个完整的工作台。
开分支，安装 Recharts，先读官方入门
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/dashboard
npm install recharts
npm ls recharts打开 Recharts 入门页 和 Chart size 页，看一遍示例代码。
npm ls recharts 显示的版本不低于 3.3，可以使用 responsive 属性。如果低于 3.3，需求卡里改成用 ResponsiveContainer。在开发库里造 8 周的假数据
打开 Neon 控制台的 SQL Editor，确认连接的是开发用的数据库，运行：
INSERT INTO click_events (platform, visitor_id, created_at)
SELECT (ARRAY['XIAOHONGSHU','TIKTOK','FACEBOOK','INSTAGRAM'])[1 + floor(random() * 4)::int]::social_platform,
'fake-' || g,
now() - random() * interval '56 days'
FROM generate_series(1, 400) AS g;
INSERT INTO quiz_results (visitor_id, world_id, created_at)
SELECT 'fake-' || g,
(ARRAY(SELECT id FROM worlds))[1 + floor(random() * 3)::int],
now() - random() * interval '56 days'
FROM generate_series(1, 200) AS g;读法：generate_series(1, 400) 生成 1 到 400 这 400 行；每行随机挑一个平台、随机选过去 56 天里的一个时间；访客编号都以 fake- 开头，方便之后删除。
SELECT count(*) FROM click_events WHERE visitor_id LIKE 'fake-%'; 返回 400。写需求卡
dongge-web/docs/specs/day61-dashboard.md
# 需求：后台数据看板 /admin/dashboard
## 背景
每周看一次：访客多了还是少了，各平台点击怎么变，测试结果里各世界的占比。
## 要做
- lib/stats/queries.ts：weeklyClicks、weeklyQuizResults（$queryRaw，按周、时区用 REPORT_TZ，最近 8 周，
week 用 to_char 返回 YYYY-MM-DD 文字，count 转 int），clicksLast7Days（最近 7 天和再往前 7 天）。
- lib/stats/shape.ts：pivotClicks、toShares、weekLabel（纯函数，缺的平台和世界补 0）。
- components/admin/WeeklyClicksChart.tsx：分组柱状图；WorldShareChart.tsx：百分比堆叠柱状图。
都是客户端组件，用 responsive 属性，颜色按上午第 5 节固定，必须有图例。
- app/admin/dashboard/page.tsx：检查登录；关键数字、两张图、点击数据表格、每周测试人数。
## 不做
- 不做日期范围选择。不做导出。
## 验收标准
- [ ] 看板显示 8 周左右的柱子，表格里某两周两个平台的数字和我在 Neon 手算的一致。
- [ ] 百分比图每根柱子都到 100%，悬停显示带 % 的数值。
- [ ] 手机宽度下图表不溢出、没有横向滚动。
- [ ] 删除假数据后，看板显示空状态文字而不是报错。
- [ ] SQL 里没有字符串拼接，没有 $queryRawUnsafe。
## 约束
遵守 CLAUDE.md（包括统计约定里的时区）。写 Recharts 代码前先查 recharts.github.io 的当前文档。Plan、实现、审查
把「问 Claude」第一条发给 Claude。实现后读 diff，按上午第 7 节的三处重点检查：
git diff --stat
grep -rn "queryRawUnsafe" lib app || echo "没有 Unsafe"
grep -rn "::int" lib/stats核对数字
npm run dev，打开 http://localhost:3000/admin/dashboard。再到 Neon 里运行上午第 2 节的 SQL（时区换成你的）。
检查手机显示和悬停
打开开发者工具的手机模拟模式，选一个窄屏手机。把鼠标移到柱子上。
删除假数据，检查空状态
DELETE FROM click_events WHERE visitor_id LIKE 'fake-%';
DELETE FROM quiz_results WHERE visitor_id LIKE 'fake-%';写下你的“每周一个数字”
在 docs/ 下新建 weekly-review.md，写一句话：你每周最想看的一个数字是什么、它变好或变坏时你会做什么。这就是今天的验收题。
提交合并
npm run typecheck
npm test
npm run build
git add .
git commit -m "feat: 后台数据看板，按周汇总点击和测试结果"
git push -u origin feat/dashboard
gh pr create --fill/admin/dashboard 能打开，显示真实的数据（可能还很少）。count(*) 没有加 ::int，返回的 BigInt 没法传给客户端组件。BarChart 上有没有 responsive 和带 aspectRatio 的 style；Recharts 版本低于 3.3 时 responsive 不起作用，要改用 ResponsiveContainer。"use client"。GROUP BY 里又写了一遍。改成 GROUP BY 1, 2。@@map 确认名字拼写。看板上你最想每周看的一个数字是什么？为什么？
没有标准答案，但好的答案要说清“这个数字会影响我的什么决定”。例如：“我最想看最近 7 天小红书按钮的点击数，因为小红书是我主要写图文的平台；如果连续两周下降，我会回头看那两周发的内容和文案助手的草稿，找出区别。”或者：“我最想看测试结果里‘街头’的占比，它上升说明观众对街头世界更有共鸣，我会多拍 BMX 和滑板。”只说“总点击数，因为想知道有多少人来”就不够，因为它没有连到任何行动上。
SQL 里为什么要写 count(*)::int？不写会怎样？
PostgreSQL 的 count 返回 64 位整数，Prisma 会把它转成 JavaScript 的 BigInt。页面把数据作为 props 传给客户端图表组件时，Next.js 需要把数据序列化，而 BigInt 不能被序列化，页面会报错。转成 int 后就是普通数字，对你的数据量来说也绝不会溢出。
在 $queryRaw 模板里写 ${REPORT_TZ}，和用加号把时区拼进 SQL 字符串，有什么区别？
$queryRaw 的模板会把每个 ${...} 变成参数，和 SQL 语句分开发给数据库，数据库只把它当数据，不会执行，所以不会有 SQL 注入。用加号拼接则是把值直接写进 SQL 文本，值里如果有引号或恶意语句就会被当成 SQL 执行。这里的时区虽然是你自己写的常量，也要养成始终用参数的习惯。
这一周你做了很多东西：对话页、文案助手、草稿箱、看板，加上 DAY 48 的 looks 管理和 DAY 50 的提问箱审核。它们现在是一个个独立的页面，要靠手动输入网址才能打开，每个页面的边距和标题样式也不太一样，有的页面检查了登录，有的依赖 DAY 47 的保护。
这就像你的拍摄器材都在，但散落在家里各个角落：斯诺克杆在客厅，BMX 在阳台，拳套在衣柜。每次拍摄前都得找一圈。今天要做的是把它们收进一个有标签的柜子：一个入口、一套导航、统一的外观，这就是「东哥内容工作台」。
今天几乎不写新功能，而是整理。整理的价值不容易被看见，但它决定了你下个月还愿不愿意打开这个工作台，也决定了 Claude 以后改代码时能不能一下找到该改的地方。
整理有一个风险：动了很多文件，却没有自动化测试兜底（测试明天才写）。所以今天给自己定一条纪律：只搬家、不装修。文件可以移动、可以删，外观可以统一，但每个函数里面的业务逻辑一行都不改。这样出了问题，只可能是“路径不对”这类容易发现的错误，构建一跑就会报出来。想顺手“优化”某段逻辑的冲动，记下来留到以后单独做。
DAY 38 学过 layout：放在某个文件夹里的 layout.tsx，会包住这个文件夹下的所有页面。DAY 47 你已经在 app/admin/layout.tsx 里放了一条顶部导航和退出按钮，今天把它改成侧边导航，后台所有页面就自动拥有了它。
布局还有一个好处：在后台页面之间点来点去时，外壳（侧栏）保持不动，只有中间的内容区域换成新页面。所以切换很快，侧栏的滚动位置也不会丢。这也解释了下面要讲的一个特点：既然外壳不重新渲染，写在外壳里的代码也就不会每次都重新执行。
dongge-web/app/admin/layout.tsx
import AdminNav from "@/components/admin/AdminNav";
import { LogoutButton } from "./logout-button";
// 注意：这里不做登录检查。布局在页面切换时不会重新执行，
// 真正的检查写在每个 page 和每个 Server Action 里（DAY 47）。
export default function AdminLayout({ children }: { children: React.ReactNode }) {
return (
<div className="min-h-screen bg-neutral-50 md:flex">
<aside className="border-b bg-white p-4 md:w-56 md:shrink-0 md:border-b-0 md:border-r">
<p className="mb-4 font-bold">东哥内容工作台</p>
<AdminNav />
<div className="mt-4">
<LogoutButton />
</div>
</aside>
<main className="min-w-0 flex-1">{children}</main>
</div>
);
}逐段解释：
LogoutButton。md 宽度（DAY 32 学过的响应式前缀）变成左右两栏，侧栏固定 56 个单位宽，shrink-0 让它不被挤窄。min-w-0 很关键：弹性布局里的子元素默认不会比自己的内容更窄，昨天的图表宽度是跟着容器走的，没有这一句，图表可能把页面撑出横向滚动条。为什么布局不顺便检查一下登录？看起来放在布局里“一处管全部”很省事，但 Next.js 文档说明，布局在页面之间导航时会被缓存、不会重新执行，靠它挡人并不可靠；而 Server Action 和 Route Handler 是可以被直接调用的入口，根本不经过布局。所以 DAY 47 定下的规矩今天继续有效：每个后台 page.tsx 第一行调用 requireAdmin()，每个 Server Action 和 Route Handler 自己检查。保护要放在离数据最近的地方。
requireAdmin()，可能会建议“统一挪进布局、页面里删掉”。这正是上面说的陷阱，不要接受。需求卡的“不做”里要专门写明这一点。导航要知道“现在在哪一页”，才能把那一项高亮。当前网址只能在浏览器里实时读取，所以导航是一个客户端组件，用 Next.js 提供的 usePathname：
dongge-web/components/admin/AdminNav.tsx
"use client";
import Link from "next/link";
import { usePathname } from "next/navigation";
const LINKS = [
{ href: "/admin", label: "概览" },
{ href: "/admin/ai/copy", label: "文案助手" },
{ href: "/admin/drafts", label: "草稿箱" },
{ href: "/admin/ai/chat", label: "对话" },
{ href: "/admin/dashboard", label: "数据看板" },
{ href: "/admin/looks", label: "Looks" },
{ href: "/admin/questions", label: "提问箱" },
];
export default function AdminNav() {
const pathname = usePathname();
return (
<nav className="flex gap-2 overflow-x-auto md:flex-col">
{LINKS.map((link) => {
const active =
link.href === "/admin" ? pathname === "/admin" : pathname.startsWith(link.href);
return (
<Link
key={link.href}
href={link.href}
aria-current={active ? "page" : undefined}
className={`whitespace-nowrap rounded px-3 py-2 ${
active ? "bg-black text-white" : "hover:bg-gray-100"
}`}
>
{link.label}
</Link>
);
})}
</nav>
);
}要点：
LINKS 里 looks 和提问箱的路径按你 DAY 48、DAY 50 的实际路径修改。startsWith，这样在 /admin/drafts/12 编辑草稿时，“草稿箱”也是高亮的。但“概览”的地址 /admin 是所有后台地址的开头，用 startsWith 会永远高亮，所以它单独用“完全相等”判断。aria-current="page" 告诉读屏软件“这是当前页面”，视障用户也能知道自己在哪。overflow-x-auto）；电脑上变成竖排。注意分工：布局本身仍然是服务端组件（它要检查登录），只把需要读当前网址的导航拆成一个小小的客户端组件。这是 DAY 39 学过的原则：只把真正需要浏览器能力的那一小块变成客户端组件，其余部分留在服务端，发给浏览器的 JavaScript 就少，页面也更快。
首页不是把所有功能再摆一遍，而是回答“现在最需要我处理什么”。我们放三个数字和一个列表：AI 还剩几次、最近 7 天有多少点击、有几条提问等你审核，以及最近的 5 条草稿。每个数字旁边都有一个去处理的链接。
dongge-web/app/admin/page.tsx
import Link from "next/link";
import { prisma } from "@/lib/prisma";
import { DAILY_LIMIT, usedInLast24h } from "@/lib/ai/usage";
import { clicksLast7Days } from "@/lib/stats/queries";
import { requireAdmin } from "@/lib/admin";
export default async function AdminHome() {
await requireAdmin();
const [used, recentDrafts, clicks, pendingQuestions] = await Promise.all([
usedInLast24h(),
prisma.draft.findMany({ orderBy: { createdAt: "desc" }, take: 5, include: { world: true } }),
clicksLast7Days(),
prisma.question.count({ where: { status: "PENDING" } }),
]);
return (
<div className="mx-auto max-w-4xl space-y-8 p-6">
<h1 className="text-2xl font-bold">今天做点什么</h1>
<div className="grid gap-4 sm:grid-cols-3">
<Stat
label="AI 剩余次数（24 小时）"
value={`${Math.max(DAILY_LIMIT - used, 0)} / ${DAILY_LIMIT}`}
href="/admin/ai/copy"
action="去写文案"
/>
<Stat label="最近 7 天点击" value={String(clicks.recent)} href="/admin/dashboard" action="看看板" />
<Stat label="待审核提问" value={String(pendingQuestions)} href="/admin/questions" action="去审核" />
</div>
<section className="space-y-2">
<h2 className="text-lg font-bold">最近的草稿</h2>
{recentDrafts.length === 0 ? (
<p className="text-gray-500">还没有草稿，去文案助手生成第一条吧。</p>
) : (
<ul className="divide-y rounded-lg border">
{recentDrafts.map((d) => (
<li key={d.id} className="flex items-center justify-between gap-4 p-3">
<span className="truncate">{d.world.name} · {d.title}</span>
<Link href={`/admin/drafts/${d.id}`} className="shrink-0 text-sm underline">编辑</Link>
</li>
))}
</ul>
)}
</section>
</div>
);
}
function Stat({ label, value, href, action }: { label: string; value: string; href: string; action: string }) {
return (
<div className="rounded-lg border p-4">
<p className="text-sm text-gray-500">{label}</p>
<p className="mt-1 text-3xl font-bold">{value}</p>
<Link href={href} className="mt-2 inline-block text-sm underline">{action}</Link>
</div>
);
}这里几乎没有新知识，全是复用：usedInLast24h 来自 DAY 59，clicksLast7Days 来自 DAY 61，提问的 PENDING 状态来自 DAY 50。这正是把逻辑放进 lib 的好处：一个函数，两个页面都能用。Math.max(..., 0) 防止剩余次数显示成负数。Stat 是只在这个页面用的小组件，所以直接写在同一个文件里。
首页放什么、不放什么，是一个产品决定。判断标准是：这条信息会不会让你立刻去做一件事。“待审核提问 3 条”会让你点进去审核，所以放；“草稿总数 128 条”看了也不会做什么，所以不放。每个区块还要想好空的时候显示什么，比如第一次使用时还没有草稿，就给一句引导，而不是一片空白。
整理后的目录应该长这样：
app/
admin/
layout.tsx 统一外壳：侧边导航、退出按钮
page.tsx 工作台首页
ai/copy/ 文案助手（page、copy-form、actions）
ai/chat/ 对话（page、chat-box）
drafts/ 草稿箱（page、[id]/page、actions）
dashboard/page.tsx 数据看板
looks/ questions/ DAY 48、50 已有
api/
ai/chat/route.ts
track/click/route.ts
track/quiz/route.ts
components/
admin/ 多个后台页面共用的组件（导航、图表）
TrackLink.tsx 前台链接页用的上报链接
lib/
ai/ claude、prompts、copy-schema、generate-copy、usage、stream-events
stats/ queries、shape
track/ rules、visitor
admin.ts auth.ts prisma.ts
docs/
specs/ copy-eval.md prompt-log.md weekly-review.md背后的原则只有三条：
copy-form.tsx 和 actions.ts 就在 ai/copy/ 里。以后删掉这个功能，整个文件夹一删就干净了。lib 或 components。lib/ai 管和 Claude 有关的一切，lib/stats 管统计查询，lib/track 管埋点规则。rules.ts、shape.ts 不读数据库也不读 cookie，测试时不需要任何模拟；queries.ts、visitor.ts 才碰外部。明天写测试时你会体会到这种分法有多省事。然后是删代码。DAY 55 的 /api/ai/ask 接口和 /admin/ai 提问页，功能已经完全被对话页取代。留着它们没有好处，反而多一个会花钱的接口需要保护、多几份代码需要维护。随之 lib/ai/reply.ts 也没人用了。删除之前要确认没有别的地方引用：
grep -rnE "api/ai/ask|ask-box|readReply" app components lib只有这几个文件自己出现在结果里，才能放心删。删完跑一次 npm run build，如果还有地方在引用，TypeScript 会直接报错告诉你。当初写得很用心的代码，完成使命后也要舍得删，Git 历史里永远找得回来。scripts/hello-claude.mjs 可以留着，以后换 Key 时用它快速检查。
移动文件时，Git 会自动识别“这是同一个文件换了位置”，在 git status 里显示为 renamed，文件的修改历史也会跟着走。前提是移动时内容基本不变，这又是“只搬家、不装修”的一个好处：如果一边移动一边大改内容，Git 会把它当成“删了一个旧文件、新建了一个新文件”，历史就断了。
目录整理好了，要让以后的 Claude 也遵守。在 CLAUDE.md 里加一节目录约定，这是 L4 阶段你最重要的产出之一：你不再逐行写代码，但你定规矩。
dongge-web/CLAUDE.md（追加）
## 目录约定
- 后台页面都在 app/admin 下，共用 app/admin/layout.tsx（导航和退出按钮）。新后台页面要加进 components/admin/AdminNav.tsx。
- 只被一个页面用的组件和 actions 放在该页面的文件夹里；多个后台页面共用的组件放 components/admin。
- 业务逻辑按功能放 lib/ai、lib/stats、lib/track。纯函数（不读数据库、不读 cookie）和有副作用的代码分文件放。
- 布局不做登录检查（原因见 DAY 47）。每个后台 page.tsx 第一行调用 requireAdmin()；每个 Server Action 和 Route Handler 自己检查登录。
- 文件命名沿用已有习惯：components 里的组件文件大写开头（PlatformButton.tsx、AdminNav.tsx）；app 下页面文件夹里的组件小写加短横线（copy-form.tsx、logout-button.tsx）。
- 需求卡放 docs/specs，文件名 dayNN-功能.md。今天的验收题是：让 Claude 通读代码，指出结构上最该改的一处，你同意吗？这道题考的不是 Claude，而是你的判断力。Claude 的建议可能很有道理，也可能是“教科书上的好做法，但对你的项目没必要”。用这四个问题来判断：
举两个例子。如果 Claude 说“三个世界的名字和感受在 copy-form.tsx 的 WORLDS 和 prompts.ts 的 WORLD_BRIEFS 里各写了一份，建议合并成一份”，这是真实的重复，改动小，值得接受。但要多想一步：copy-form.tsx 是客户端组件，如果它直接引入 prompts.ts，整份系统提示词都会被打包进浏览器。更好的做法是把世界资料单独放进一个小文件（比如 lib/worlds.ts），两边都从这里引入。接受建议，也要检查建议的具体做法。如果它说“建议引入依赖注入容器，把所有数据库访问抽象成仓储层”，对一个人用的后台来说是过度设计，可以礼貌地拒绝，并写下理由。
还要注意一点：Claude 给出的“最该改的一处”，和你自己心里觉得最别扭的地方，可能不是同一处。两者都值得记下来。如果你觉得某个文件每次都找不到、某段代码每次都看不懂，那往往比 Claude 从外部看到的问题更真实，因为你才是每天用这个工作台的人。
不管接受还是拒绝，都把结论和理由写进 PR 的描述里。几个月后回看，你会清楚当时为什么这样决定。明天，我们给 AI 功能写测试，然后正式上线自用。
开分支，写需求卡
cd ~/code/dongge-web
git switch main
git pull
git switch -c feat/workbenchdongge-web/docs/specs/day62-workbench.md
# 需求：合并成「东哥内容工作台」
## 背景
后台功能分散，没有导航。整理成一个工作台，并清理不再使用的代码。
## 要做
- app/admin/layout.tsx：把 DAY 47 的顶部导航改成侧边导航，保留退出按钮和“这里不做登录检查”的注释。
- components/admin/AdminNav.tsx：usePathname 高亮当前项；“概览”只在 /admin 完全匹配时高亮。
- app/admin/page.tsx：替换 DAY 47 的后台首页，改成工作台首页：三个数字（AI 剩余次数、最近 7 天点击、待审核提问）+ 最近 5 条草稿；第一行 requireAdmin()。
- 按上午第 5 节整理目录。移动文件后更新所有 import。
- 删除 /api/ai/ask、/admin/ai 提问页、ask-box.tsx、lib/ai/reply.ts（先确认没有其他引用）。
- 各页面去掉重复的外层边距和标题样式，外观统一。
## 不做
- 不加新功能，不改业务逻辑，不改提示词。
- 布局里不加登录检查；页面、Server Action、Route Handler 里的登录检查一个都不能删，也不能挪进布局。
## 验收标准
- [ ] 后台任意页面左侧（手机上是顶部）都有导航，当前页高亮；进入草稿编辑页时“草稿箱”高亮。
- [ ] 退出登录后访问 /admin/drafts 和 /admin/dashboard，都跳到登录页。
- [ ] app/admin 下每个 page.tsx 都调用了 requireAdmin()（用 grep -L 检查，没有输出）。
- [ ] 首页三个数字和各自页面上的数据一致，链接都能点通。
- [ ] 手机宽度下导航可以左右滑动，看板图表没有撑出横向滚动条。
- [ ] 访问 /api/ai/ask 返回 404。
- [ ] npm run build 和 npm test 都通过。
## 约束
遵守 CLAUDE.md。这是整理，不是重写：每个文件的业务逻辑保持不变。Plan：先看文件移动和删除清单
把「问 Claude」第一条发给 Claude。它给出的方案里要有一张清单：哪些文件移动到哪里、哪些文件删除。逐条确认，特别是删除的那几项，自己先跑一次上午第 5 节的 grep 核对。
实现后审查 diff
git status
git diff --stat
git diff app/admin/layout.tsx components/admin/AdminNav.tsxgit status 里会看到很多 renamed（移动）和 deleted（删除）。重点确认：每个 Server Action 和 Route Handler 里的登录检查都还在；删掉的只有需求卡里列出的文件。
grep -rnE "getAdminSession|requireAdmin" app lib
grep -L "requireAdmin" $(find app/admin -name "page.tsx")第二条命令列出 app/admin 下所有“没有出现 requireAdmin”的 page.tsx（-L 表示只列出不匹配的文件）。
跑构建和测试
npm run typecheck
npm test
npm run build逐页点一遍
npm run dev，登录后从首页开始，依次点导航里的每一项，再进入一条草稿的编辑页。然后退出登录，直接在地址栏输入 http://localhost:3000/admin/drafts。
检查手机显示和被删除的接口
开发者工具切到手机模拟模式，看首页和看板。再测被删除的接口：
curl -i -X POST http://localhost:3000/api/ai/ask \
-H "Content-Type: application/json" \
-d '{"question":"你好"}'404。更新 CLAUDE.md
把上午第 6 节的“目录约定”加进 CLAUDE.md。这一步你自己写，写完读一遍，看看有没有和前面“AI 功能约定”“统计约定”矛盾的地方。
做今天的验收：结构审查
新开一个 Claude Code 对话（让它不受今天整理过程的影响），发送「问 Claude」第二条。拿到建议后，用上午第 7 节的四个问题逐一回答，决定接受或拒绝。接受的话，另开一个分支做，不要混进今天的 PR。
提交，PR 描述里写上审查结论
git add .
git commit -m "refactor: 合并为东哥内容工作台，统一导航并清理旧代码"
git push -u origin feat/workbench
gh pr create --fillPR 创建后，在 GitHub 上编辑描述，加一段“结构审查结论”，把上一步的内容贴进去。CI 通过后合并。
await requireAdmin()。布局不做检查，所以每个新页面都要自己加。用下午第 3 步的 grep -L 命令，一次找出所有漏掉的页面。/admin 开头，用 startsWith 判断就永远为真。给 /admin 单独用完全相等判断。main 上漏了 min-w-0。弹性布局的子元素默认不会缩得比内容更窄。grep -rn "旧路径" app components lib 找出来改掉。以后在 VS Code 里拖动文件时，它会询问是否自动更新 import，选“是”。让 Claude 通读代码，指出结构上最该改的一处。你同意吗？为什么？
答案取决于 Claude 实际给出的建议，重点是你的判断过程。好的回答会复述建议（比如“把世界资料合并成一份，放进单独的 lib/worlds.ts”），然后用四个问题回答：它解决的是真实遇到的问题吗；改动多大、有没有测试保护；改完我还看得懂吗；不改会怎样。最后给出结论，比如“同意，重复是真实的，改动只涉及 3 个文件，但不能让客户端组件引入 prompts.ts，明天写完测试后再做”，或者“不同意，引入仓储层对一个人用的后台是过度设计，现在的结构我能看懂，也没遇到问题”。只写“同意，Claude 说得对”不算合格。
为什么后台布局里不做登录检查，而是每个页面、每个 Server Action 和 Route Handler 各自检查？
布局只在渲染页面时运行，而且在页面之间导航时会被缓存、不会重新执行，靠它挡人不可靠。Server Action 和 Route Handler 是独立的入口，任何人都可以不打开页面、直接发请求调用它们，这些请求根本不经过布局。所以保护必须放在每个会读写数据或调用 Claude 的入口里：页面第一行 requireAdmin()，Action 和接口开头各自检查。重复写几行，换来的是每个入口都不依赖别处，漏了一处也不会全盘失守。
为什么要删掉 DAY 55 写的 /api/ai/ask？删除之前你做了哪些确认？
它的功能已经被流式对话页完全取代，留着只会多一个会花钱、需要保护的接口，多一份需要维护的代码，没有任何好处。删除前用 grep 搜索 api/ai/ask、ask-box、readReply，确认只有要删的文件自己引用自己；删除后跑 npm run build 和 npm test，没有报错才算安全；最后用 curl 确认接口返回 404。代码删了也能从 Git 历史里找回来。
vi.mock 和 vi.hoisted 模拟 Claude 客户端，测试 generateCopy 的成功、拒答、截断、出错四种情况，并检查请求参数。refusal，输入不合法时不调用 Claude。/code-review 修完高优先级问题，按清单上线，接下来一周真的用工作台写文案。「东哥内容工作台」已经合并好了，今天是上线日。上线前要做的最后一件事，是给 AI 功能写自动化测试，让以后每次改代码时 CI 都能帮你检查有没有改坏。
问题是：测试里要不要真的调用 Claude？答案是不要，原因有四个：
解决办法是模拟（mock）：测试时把真正的 Claude 客户端换成一个“替身”，替身按你的剧本返回结果。就像拍视频排练走位时，不用请真的对手来打一场泰拳，找个同伴站在那个位置、按约定出拳就行。你要检查的是“自己的反应对不对”，不是对手打得好不好。
所以要分清楚：测试检查的是你的代码怎样对待 Claude 的各种返回，比如拒答时有没有给出提示、截断时有没有丢掉半截内容、参数有没有带上兜底；Claude 写得好不好，是评估的事，DAY 58 和 DAY 59 你已经用人工打分做过了。两者互相不能代替。
你可能会想到 DAY 52 的 Playwright 端到端测试：模拟真人点页面，不是更真实吗？对 AI 功能来说，端到端测试会一路走到真正的 Claude 调用，又回到了花钱和结果不固定的老问题。所以分工是：单元测试加替身，负责检查各种分支；上线后亲手走一遍，负责确认真实链路是通的。
测试不是越多越好，要挑那些“以后不小心改坏了会出事、而且你自己很难发现”的行为。对照这一周写的代码，最值得测的是：
| 代码 | 要测的行为 | 为什么重要 |
|---|---|---|
generateCopy | 拒答、截断、API 出错、解析失败都返回中文提示；正常时返回草稿和用量 | 这些分支平时几乎碰不到，改坏了也不会马上发现 |
generateCopy 的请求参数 | 用 MODEL、带 fallbacks、没有 temperature | 这是 CLAUDE.md 里的硬规矩，Claude 改代码时可能“顺手”改掉 |
| 对话接口 | 每段文字一行、最后一行是 done 和 stop_reason；输入不合法不调用 Claude | 前端依赖这个协议；不合法输入还调用 Claude 就是白花钱 |
| 埋点规则 | 窗口内算重复，正好到窗口边界不算；机器人识别 | 边界条件最容易写错一个等号 |
| 看板数据整理 | 按周合并、缺的补 0、百分比计算 | 看板数字错了你不一定看得出来 |
还记得 DAY 55 为什么要把客户端统一放进 lib/ai/claude.ts 的 getClaude() 吗？今天它派上用场了：只要把这一个模块换成替身，所有用到 Claude 的代码就都用上了替身。
dongge-web/lib/ai/generate-copy.test.ts
import { beforeEach, describe, expect, it, vi } from "vitest";
import Anthropic from "@anthropic-ai/sdk";
// 1. server-only 在测试环境里会报错，换成一个空模块
vi.mock("server-only", () => ({}));
// 2. 先准备一个“替身函数”，vi.hoisted 保证它在 vi.mock 之前就创建好
const { parseMock } = vi.hoisted(() => ({ parseMock: vi.fn() }));
// 3. 把整个 @/lib/ai/claude 换成替身
vi.mock("@/lib/ai/claude", () => ({
MODEL: "claude-opus-5",
FALLBACK_BETA: "server-side-fallback-2026-07-01",
getClaude: () => ({ beta: { messages: { parse: parseMock } } }),
}));
import { generateCopy } from "@/lib/ai/generate-copy";
const sample = {
xiaohongshu: { title: "差一颗黑球", body: "最后一颗黑球停在袋口。", tags: ["斯诺克", "周末日常"] },
tiktok: { title: "差一颗", body: "黑球停在袋口。", tags: ["snooker"] },
};
// 造一个假的 Claude 响应，默认是正常结束
function fakeMessage(overrides: Record<string, unknown> = {}) {
return {
model: "claude-opus-5",
stop_reason: "end_turn",
content: [],
parsed_output: sample,
usage: { input_tokens: 1200, output_tokens: 800 },
...overrides,
};
}
const input = { world: "gentleman" as const, topic: "第一次打满一局斯诺克" };
describe("generateCopy", () => {
beforeEach(() => {
parseMock.mockReset();
vi.spyOn(console, "error").mockImplementation(() => {});
});
it("正常结束时返回两版草稿和用量", async () => {
parseMock.mockResolvedValueOnce(fakeMessage());
const result = await generateCopy(input);
expect(result).toEqual({ ok: true, data: sample, usage: { input: 1200, output: 800 } });
});
it("拒答时返回提示，即使响应里有 parsed_output 也不使用", async () => {
parseMock.mockResolvedValueOnce(fakeMessage({ stop_reason: "refusal" }));
const result = await generateCopy(input);
expect(result.ok).toBe(false);
});
it("被截断时返回提示", async () => {
parseMock.mockResolvedValueOnce(fakeMessage({ stop_reason: "max_tokens" }));
expect((await generateCopy(input)).ok).toBe(false);
});
it("网络或服务出错时返回中文提示，而不是抛出异常", async () => {
parseMock.mockRejectedValueOnce(new Anthropic.APIConnectionError({ message: "网络断了" }));
expect(await generateCopy(input)).toEqual({ ok: false, message: "AI 服务暂时不可用，稍后再试。" });
});
it("SDK 解析 JSON 失败时返回格式不完整的提示", async () => {
parseMock.mockRejectedValueOnce(new Anthropic.AnthropicError("Failed to parse structured output"));
expect(await generateCopy(input)).toEqual({ ok: false, message: "这次生成的格式不完整，请再试一次。" });
});
it("请求参数符合 CLAUDE.md 的约定", async () => {
parseMock.mockResolvedValueOnce(fakeMessage());
await generateCopy({ world: "thai", topic: "泰拳课后帮新学员缠手带" });
const params = parseMock.mock.calls[0][0];
expect(params.model).toBe("claude-opus-5");
expect(params.fallbacks).toBe("default");
expect(params.betas).toContain("server-side-fallback-2026-07-01");
expect(params).not.toHaveProperty("temperature");
expect(params.messages[0].content).toContain("泰拳课后帮新学员缠手带");
expect(params.messages[0].content).toContain("泰风");
});
});为什么替换的是我们自己的 @/lib/ai/claude，而不是直接替换 @anthropic-ai/sdk？SDK 是一个很大的库，内部结构随版本变化，直接模拟它，测试就会依赖很多你不了解的细节，SDK 一升级测试就可能莫名其妙地坏掉。我们自己的模块只有 MODEL、FALLBACK_BETA 和 getClaude() 三样东西，边界小而稳定，替换起来简单明了。这也是一条通用的经验：在你自己划定的边界上模拟，而不是深入别人的代码内部。
逐段解释：
vi.mock("server-only", ...)：server-only 这个包在 Next.js 之外被引入时会直接报错，而测试不是在 Next.js 里跑的，所以把它换成一个什么都没有的空模块。vi.mock 会被“提升”：Vitest 文档说明，vi.mock 无论写在哪里，都会被挪到文件最前面、在所有 import 之前执行。这样 generate-copy.ts 引入 @/lib/ai/claude 时，拿到的已经是替身。但这也带来一个问题：替身工厂函数里如果用到外面定义的变量，那个变量那时还没创建。vi.hoisted 就是解决这个问题的：它里面的代码也会被提升，保证 parseMock 在 vi.mock 之前就准备好了。vi.fn()：一个可以被“编排”的假函数。mockResolvedValueOnce(x) 表示“下一次被调用时，返回一个结果为 x 的 Promise”；mockRejectedValueOnce(err) 表示“下一次调用时抛出这个错误”。mock.calls[0][0] 是第一次调用时的第一个参数，也就是 generateCopy 发给 Claude 的完整请求。beforeEach：每个测试开始前清空替身的剧本和调用记录，免得上一个测试影响下一个。顺手把 console.error 静音，否则出错分支的日志会刷满终端。refusal，但 parsed_output 里仍然放着完整的草稿。如果有人把代码改成“先读 parsed_output 再看 stop_reason”，这个测试就会失败。这就是“测试守住规矩”的意思。APIConnectionError 是 APIError 的一种（网络连不上），AnthropicError 是通用错误。这样测的正是代码里 instanceof 的判断顺序。对话接口更复杂：它调用的是 stream()，返回的对象要能被 for await 循环读取，还要有 finalMessage() 和 abort()。我们就按这个形状造一个替身。另外它还用到了登录检查和用量限制，这两个模块也要换成替身，否则测试会去连数据库。
dongge-web/app/api/ai/chat/route.test.ts
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("server-only", () => ({}));
const { streamMock } = vi.hoisted(() => ({ streamMock: vi.fn() }));
vi.mock("@/lib/ai/claude", () => ({
MODEL: "claude-opus-5",
FALLBACK_BETA: "server-side-fallback-2026-07-01",
getClaude: () => ({ beta: { messages: { stream: streamMock } } }),
}));
vi.mock("@/lib/admin", () => ({
getAdminSession: vi.fn(async () => ({ user: { id: "dongge" } })),
}));
vi.mock("@/lib/ai/usage", () => ({
DAILY_LIMIT: 30,
usedInLast24h: vi.fn(async () => 0),
recordUsage: vi.fn(async () => {}),
}));
import { POST } from "@/app/api/ai/chat/route";
// 假的事件流：依次吐出几段文字，最后给出 stop_reason
function fakeStream(texts: string[], stopReason: string) {
return {
async *[Symbol.asyncIterator]() {
for (const text of texts) {
yield { type: "content_block_delta", index: 0, delta: { type: "text_delta", text } };
}
},
finalMessage: async () => ({
stop_reason: stopReason,
usage: { input_tokens: 10, output_tokens: 20 },
}),
abort: vi.fn(),
};
}
function chatRequest(body: unknown) {
return new Request("http://localhost/api/ai/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
}
async function readEvents(res: Response) {
const text = await res.text();
return text.trim().split("\n").map((line) => JSON.parse(line));
}
describe("POST /api/ai/chat", () => {
beforeEach(() => {
streamMock.mockReset();
});
it("每段文字推一行，最后一行是 done", async () => {
streamMock.mockReturnValueOnce(fakeStream(["下午", "雨停了"], "end_turn"));
const res = await POST(chatRequest({ messages: [{ role: "user", content: "写一句开头" }] }));
expect(res.headers.get("Content-Type")).toContain("application/x-ndjson");
expect(await readEvents(res)).toEqual([
{ type: "text", text: "下午" },
{ type: "text", text: "雨停了" },
{ type: "done", stopReason: "end_turn" },
]);
});
it("中途被拒时，最后一行的 stopReason 是 refusal", async () => {
streamMock.mockReturnValueOnce(fakeStream(["半截"], "refusal"));
const res = await POST(chatRequest({ messages: [{ role: "user", content: "你好" }] }));
const events = await readEvents(res);
expect(events.at(-1)).toEqual({ type: "done", stopReason: "refusal" });
});
it("最后一条不是用户的提问时返回 400，并且不调用 Claude", async () => {
const res = await POST(chatRequest({ messages: [{ role: "assistant", content: "我先说" }] }));
expect(res.status).toBe(400);
expect(streamMock).not.toHaveBeenCalled();
});
});要点：
// @vitest-environment node：告诉 Vitest 这个文件用 Node 环境跑。Route Handler 是服务端代码，要用 Node 自带的 Request、Response 和 ReadableStream。DAY 51 的 vitest.config.mts 已经把默认环境设成了 node，这一行是保险：以后如果为了测试 React 组件把默认环境改成模拟浏览器，这个文件仍然在 Node 里跑。async *[Symbol.asyncIterator]()：看起来吓人，意思其实很简单：“这个对象可以被 for await 一个一个地读”。async * 是异步生成器，每个 yield 产出一个事件，形状和真实 SDK 的 content_block_delta 事件一样，所以接口代码分不出真假。POST：Route Handler 就是一个普通的异步函数，接收一个 Request、返回一个 Response。测试里自己 new Request(...) 传进去，不需要启动服务器。res.text()：把整个流读完变成字符串，再按换行切开、逐行解析。这正好也验证了“每行一个 JSON”的协议。not.toHaveBeenCalled() 证明替身一次都没被调用。替身也有风险：它只长成“你以为 SDK 会返回的样子”。如果将来 SDK 升级改变了事件的形状，替身还是旧样子，测试照样全绿，线上却出了问题。所以替身的形状要照着官方文档写（我们的 content_block_delta 和 text_delta 就来自本地 SDK 文档里的事件表），并且每次升级 @anthropic-ai/sdk 之后，都要在本地亲手用一次对话页和文案助手，不能只看测试结果。
DAY 60 和 DAY 61 特意把规则和数据整理写成了纯函数，今天收获回报：它们的测试不需要任何替身，给输入、看输出就行。
dongge-web/lib/track/rules.test.ts
import { describe, expect, it } from "vitest";
import { isDuplicate, looksLikeBot } from "@/lib/track/rules";
describe("isDuplicate", () => {
const now = new Date("2026-09-25T12:00:00Z");
it("没有上一条记录时不算重复", () => {
expect(isDuplicate(null, now, 30)).toBe(false);
});
it("29 分钟前记录过，算重复", () => {
expect(isDuplicate(new Date("2026-09-25T11:31:00Z"), now, 30)).toBe(true);
});
it("正好 30 分钟前记录过，不算重复", () => {
expect(isDuplicate(new Date("2026-09-25T11:30:00Z"), now, 30)).toBe(false);
});
});
describe("looksLikeBot", () => {
it("没有 User-Agent 当作机器人", () => {
expect(looksLikeBot(null)).toBe(true);
});
it("识别常见爬虫", () => {
expect(looksLikeBot("Mozilla/5.0 (compatible; Googlebot/2.1)")).toBe(true);
});
it("普通手机浏览器不是机器人", () => {
expect(
looksLikeBot("Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148"),
).toBe(false);
});
});dongge-web/lib/stats/shape.test.ts
import { describe, expect, it } from "vitest";
import { pivotClicks, toShares, weekLabel } from "@/lib/stats/shape";
describe("看板数据整理", () => {
it("weekLabel 把日期变成 月/日", () => {
expect(weekLabel("2026-09-07")).toBe("9/7");
});
it("pivotClicks 按周合并，缺的平台补 0", () => {
const rows = [
{ week: "2026-09-14", platform: "XIAOHONGSHU", clicks: 12 },
{ week: "2026-09-14", platform: "TIKTOK", clicks: 5 },
{ week: "2026-09-21", platform: "XIAOHONGSHU", clicks: 9 },
];
expect(pivotClicks(rows)).toEqual([
{ week: "9/14", XIAOHONGSHU: 12, TIKTOK: 5, FACEBOOK: 0, INSTAGRAM: 0 },
{ week: "9/21", XIAOHONGSHU: 9, TIKTOK: 0, FACEBOOK: 0, INSTAGRAM: 0 },
]);
});
it("toShares 把次数换成百分比，并保留总人数", () => {
const rows = [
{ week: "2026-09-21", world: "gentleman", total: 1 },
{ week: "2026-09-21", world: "street", total: 3 },
];
expect(toShares(rows)).toEqual([{ week: "9/21", total: 4, gentleman: 25, street: 75, thai: 0 }]);
});
});“正好 30 分钟”这种边界测试特别有价值：代码里写的是 <，如果有人改成 <=，行为就变了，这个测试会立刻发现。测试文件的位置沿用 DAY 51 的习惯：和被测文件放在一起，以 .test.ts 结尾，vitest.config.mts 的 include 只认这种文件；DAY 52 的 Playwright 测试在 e2e/ 里、以 .spec.ts 结尾，两者互不干扰。对话接口的测试放在 app/api/ai/chat/route.test.ts，Next.js 只把名字正好是 route.ts 的文件当成接口，测试文件不会变成网址。
测试写完、全部通过后，在 Claude Code 里运行 /code-review，让它审查这一周的改动。和 DAY 54 一样，处理原则是：高优先级的问题（安全、数据错误、会花冤枉钱的逻辑）必须修；中低优先级的按 DAY 62 的四个问题判断，不改的写下理由。
然后按这张清单上线。每一项都要亲手确认，不能凭印象：
ANTHROPIC_API_KEY，而且用的是线上那把 Key。npx prisma migrate status 查看）。DAILY_LIMIT 的数值是你想要的。万一上线后出问题怎么办？先去 Vercel 项目的 Logs 里看报错，我们在代码里用 console.error 打印的内容都会出现在那里。如果一时修不好，最快的止损办法有两个：用 git revert 撤销出问题的那次合并，推上去让 Vercel 重新部署；或者临时把 DAILY_LIMIT 改成 0，AI 功能全部停用，但前台和后台其他功能照常工作。先止损，再慢慢查原因。
这个阶段的验收题是“用工作台生成的文案，至少有一条真的发出去了”。这不是走形式：一个工具只有被真正使用，你才知道它哪里好用、哪里别扭。建议接下来一周这样用：
docs/weekly-review.md 里记一笔：用了几次、发了几条、哪条草稿改得最多、哪里用着别扭。一周后，这份记录就是 DAY 64 写正式版需求文档最好的材料。你会发现，最有价值的需求往往不是“再加一个酷炫功能”，而是“这个按钮每次都要找半天”“生成的 TikTok 标题我每次都要改”这种来自真实使用的小事。到这里，你已经从一个零基础的学员，变成了能写需求、定规矩、审查代码、用数据做决定的产品负责人。
开分支，写需求卡
cd ~/code/dongge-web
git switch main
git pull
git switch -c test/ai-featuresdongge-web/docs/specs/day63-tests.md
# 需求：给 AI 功能和统计逻辑写测试
## 背景
上线前补齐自动化测试，防止以后改代码时悄悄改坏拒答处理、请求参数和统计规则。
## 要做
- lib/ai/generate-copy.test.ts：正常、拒答（响应里仍带 parsed_output）、截断、APIConnectionError、
AnthropicError（解析失败）五种情况；再加一条检查请求参数（model、fallbacks、betas、无 temperature、用户消息含主题和世界名）。
- app/api/ai/chat/route.test.ts：文字逐行 + done；refusal 时最后一行 stopReason 为 refusal；
最后一条不是用户消息时返回 400 且不调用 stream。
- lib/track/rules.test.ts 和 lib/stats/shape.test.ts：见上午第 5 节，包含边界情况。
- 测试文件和被测文件放在一起，以 .test.ts 结尾（沿用 DAY 51 的 vitest.config.mts）。
## 不做
- 不修改被测试的业务代码。如果发现 bug，先写一条会失败的测试，再告诉我，由我决定怎么修。
- 不真的调用 Claude API，不连数据库。
## 验收标准
- [ ] npm test 全部通过。
- [ ] 把 generate-copy.ts 里的 refusal 判断临时注释掉，至少一个测试失败；恢复后全部通过。
- [ ] 把 rules.ts 里的 < 临时改成 <=，边界测试失败；恢复后通过。
- [ ] 在没有 ANTHROPIC_API_KEY 的环境下测试也能全部通过（说明没有真的调用 API）。
- [ ] 每个测试的名字用中文写清楚在验证什么行为。
## 约束
只允许模拟 server-only、@/lib/ai/claude、@/lib/admin、@/lib/ai/usage 这几个模块。Plan、实现、审查测试本身
把「问 Claude」第一条发给 Claude。审查测试代码时，重点看两件事：测试名是否说清了行为；断言是否真的在检查行为（比如 toEqual 了具体的提示语、检查了 not.toHaveBeenCalled），而不是只写了 expect(result).toBeDefined() 这种什么都证明不了的断言。
运行测试，并确认没有真的调用 API
npm test
ANTHROPIC_API_KEY= npm test第二条命令在运行测试时把 Key 设成空。如果某个测试漏掉了替身、真的去调用 Claude，它会因为 getClaude() 报“缺少 ANTHROPIC_API_KEY”而失败。
故意改坏，确认测试会拦住
打开 lib/ai/generate-copy.ts，把 if (message.stop_reason === "refusal") { ... } 这三行临时注释掉，运行 npm test。再恢复，把 lib/track/rules.ts 里 isDuplicate 的 < 改成 <=，再运行一次。
git diff lib 没有任何输出，测试全部通过。跑 /code-review
在 Claude Code 里输入 /code-review。把结果分成三类记下来：必须修的高优先级问题、打算修的、决定不修的（写理由）。高优先级的问题写一张小需求卡交给 Claude 修，修完再跑一遍测试。
提交并合并
npm run typecheck
npm test
npm run build
git add .
git commit -m "test: AI 功能和统计逻辑的单元测试"
git push -u origin test/ai-features
gh pr create --fill按上线清单逐项确认
对照上午第 6 节的清单，一项一项确认：Vercel 环境变量、正式库迁移状态、Console 用量上限、DAILY_LIMIT、CI 状态。每确认一项，就在 docs/weekly-review.md 顶部写一行“上线检查：……已确认”。
在线上走一遍完整流程
用电脑登录线上后台：工作台首页，生成一条真实视频的文案，在草稿箱修改并收藏，在对话页问一个问题并中途停止。再用手机打开你的链接页，点一个平台按钮，做一遍测试小游戏。最后回到后台首页和看板。
开始一周的真实使用
从今天起，每条视频的文案都先用工作台生成草稿，改好后发出去，并在草稿箱里标记“已发布”。每天在 docs/weekly-review.md 记一笔：
## 第 1 天（日期）
- 生成 2 次，发布 1 条（小红书，绅士/斯诺克）
- 改动最大的地方：小红书标题，原版太像广告
- 用着别扭：生成中不能切到别的页面，否则结果看不到vi.mock 的工厂函数里用了普通的外部变量。vi.mock 会被提升到最前面，那时变量还没创建。用 vi.hoisted 创建替身函数。vi.mock("server-only", () => ({}))。凡是被测代码直接或间接引入了 server-only 的测试文件都要加。@/ 这个路径别名。确认 vitest.config.mts 里还有 DAY 51 加的 tsconfigPaths() 插件，它让 Vitest 读取 tsconfig.json 里的路径设置。vitest.config.mts 的默认环境。确认测试文件第一行是 // @vitest-environment node，前面不能有别的代码。vi.mock("@/lib/ai/claude", ...)，并用 ANTHROPIC_API_KEY= npm test 复查。用工作台生成的文案，至少有一条真的发出去了。
这是一道实践题，证据有三样：草稿箱“已发布”筛选里有那条草稿，并且有发布时间；平台上能看到这条真实发布的内容；docs/weekly-review.md 里记下了你把草稿改了哪些地方、为什么改。如果一周过去一条都没发出去，也要诚实记录原因（比如“草稿每次都要大改，不如自己写”），这本身就是 DAY 64 最重要的需求输入：说明提示词或功能需要调整。
为什么给 AI 功能写测试时要模拟 SDK，而不是真的调用 Claude？模拟之后，测试能证明什么、不能证明什么？
真调用会花钱、结果每次不同没法断言、CI 里没有也不该有 Key、速度慢，而且拒答和截断这些分支根本没法按需触发。模拟之后，测试能证明“你的代码在收到各种返回时做了正确的事”：拒答给提示、截断不用半截内容、出错不崩溃、参数带着兜底且没有采样参数、流式协议正确。它不能证明 Claude 真的会按这个格式返回、也不能证明文案写得好，前者靠官方文档和上线后的实际运行，后者靠 DAY 58、59 那样的人工评估。
“拒答时返回提示”这个测试，为什么故意在 refusal 的假响应里也放了完整的 parsed_output？
为了让测试真正守住“先看 stop_reason，再读内容”这条规矩。如果假响应里 parsed_output 是空的，那么就算代码改成先读 parsed_output，也会因为它是空的而返回失败，测试照样通过，发现不了问题。放上完整的草稿之后，只有“先检查 stop_reason”的代码才能让测试通过，顺序一旦被改错，测试立刻失败。
CLAUDE.md，说清技术栈、目录结构、常用命令、代码规范和协作方式，并解释每一段为什么要写。README.md，让一个没见过这个项目的人照着它在 15 分钟内把网站在本地跑起来。gh label create 和 gh issue create 把方案拆成 GitHub issue。到昨天为止，~/code/dongge-web 已经是一个完整的网站：前台有三个世界、链接页、测试小游戏和提问箱；后台有 looks 管理、提问审核、AI 文案助手和数据看板；还有 Vitest、Playwright 测试和 GitHub Actions CI，部署在 Vercel。接下来 8 天，重点不再是“加功能”，而是把它打磨成可以放进小红书、TikTok、Facebook、Instagram 简介里的正式版：打开快、分享好看、不怕被刷、出了错能查到、有自己的域名。
这一阶段 Claude 的角色是 L4“你来指挥”。打个比方：装修房子时，你是业主兼监理，Claude 是施工队。施工队手艺很好，但它不知道你家几口人、预算多少、哪面墙不能动。你不说清楚，它只能按“一般人家”的习惯来装，装完你才发现不对，返工最费钱。指挥做得好不好，看三样东西：
之后每个任务都走同一个循环：你写 issue（需求加验收标准）；Claude 在新分支上实现；你读 diff、跑测试、按验收标准亲手点一遍；通过就合并 Pull Request，不通过就把问题写清楚让它改。注意最后一步永远是你。Claude 可以写代码，但“合并进 main、上线给粉丝看”这个决定只能由你来做，因为出了问题负责的也是你。
为什么要写成文档，而不是想到哪说到哪？因为做项目最常见的失败不是技术问题，而是“范围蔓延”：做着做着不断加“顺手的小功能”，结果每样都做了一半，哪样都上不了线。需求文档把目标写死在纸上，每次想加东西时先问一句：它在文档里吗？不在，就放进“以后再说”。
其中最有价值的一栏是“明确不做”。它看起来什么都没产出，其实是在给你和 Claude 划边界。Claude 很勤快，你说“把提问箱做完善一点”，它可能顺手加上粉丝注册、评论、点赞。有了“明确不做”，它就知道哪些事不能碰。
一份需求文档一般包含 7 部分：背景与目标、用户是谁、功能清单（保留、改进、新增、明确不做）、非功能需求（速度、安全、稳定这类“不是功能但必须满足”的要求）、验收标准、里程碑、风险与开放问题。下面是一份针对 dongge-web 的完整模板和示例，数字只是示范，换成你自己的判断。
dongge-web/docs/requirements.md
# 三岁的东哥 正式版需求文档（v1.0）
更新日期：2026-xx-xx 负责人：东哥
## 1. 背景与目标
- 背景：dongge-web 已有前台和后台，目前只有我自己在用。
- 目标：DAY 71 正式发布，把网址放进小红书、TikTok、Facebook、Instagram 简介。
- 成功的样子：发布后一周内，至少 50 位访客做完测试小游戏；
提问箱收到的每条提问都能在后台审核。
## 2. 用户是谁
- 粉丝（主要是女性）：从平台简介点进来，大多用手机，停留时间短。
- 管理员（只有我）：用电脑登录后台，审核提问、发 looks、写文案。
## 3. 功能清单
### 3.1 保留（已有，正式版原样保留）
- 首页 + 三个世界详情页（绅士 / 街头 / 泰风）
- 链接页：四个平台按钮 + 点击统计
- 测试小游戏：6 道题，结果对应一个世界
- 提问箱：粉丝提交，审核通过后前台显示
- 后台：looks 管理、提问审核、AI 文案助手、数据看板
### 3.2 改进（已有，但要做得更好）
- 首页手机端 Lighthouse 性能分 >= 90（DAY 65）
- 每个页面有自己的标题、描述和分享图；测试结果有专属分享图（DAY 66）
- 提问箱和文案助手加限流；有自定义 404 和 500 页面（DAY 67）
### 3.3 新增
- 备份恢复演练 + 故障手册 docs/runbook.md（DAY 68）
- 自己的域名，全站 HTTPS（DAY 69）
### 3.4 明确不做（正式版之后再考虑）
- 粉丝注册、登录、评论、点赞
- 英文版 / 多语言
- 手机 App
- 付费或会员功能
## 4. 非功能需求
- 速度：首页手机端 Lighthouse 性能 >= 90，LCP <= 2.5 秒
- 安全：同一 IP 10 分钟内最多提交 3 条提问；密钥只在服务端和 Vercel 环境变量里
- 稳定：出错时显示友好的错误页；能在 Vercel 日志里用错误编号找到原因
- 数据：每周至少一次 pg_dump 备份；做过一次恢复演练
## 5. 验收标准（每条都要能检验）
- [ ] 手机上做完 6 题，结果页有“分享我的结果”，点开后网址是 /quiz/result/世界名
- [ ] 把 /quiz/result/street 发到聊天软件，预览卡片上有“街头”和“心动”
- [ ] 同一台电脑 10 分钟内提交第 4 条提问，页面提示“提交太频繁”，数据库不新增
- [ ] 访问不存在的网址，显示自定义 404 页，HTTP 状态码是 404
- [ ] 未登录访问 /admin，会跳到登录页
## 6. 里程碑
| 天 | 内容 | issue |
| DAY 65 | 性能优化 | # |
| DAY 66 | 分享卡片与 SEO | # |
| DAY 67 | 安全加固 | # |
| DAY 68 | 备份、日志、故障手册 | # |
| DAY 69 | 绑定域名 | # |
| DAY 70 | 全面审查、补测试 | # |
| DAY 71 | 正式发布 | # |
## 7. 风险与开放问题
- 小红书观众多在中国大陆，Vercel 不保证大陆访问：用自己的域名，发布前请大陆朋友帮忙测试
- Claude API 按用量计费：控制台里设好每月上限
- 域名还没买：DAY 69 前自己决定买不买、买哪个逐段看为什么这样写：“成功的样子”给目标一个能数出来的数字，一周后你能判断正式版有没有达到目的。“用户是谁”提醒你粉丝多用手机、停留短，所以性能和手机体验排在前面。“改进”一栏后面标了哪天做，就是一份时间表。“非功能需求”里的数字，是明后天给 Claude 下任务时的硬指标。“里程碑”里的 issue 编号先空着，今天下午建好 issue 再填回来。“风险”一栏写的是你现在还不确定、但会影响上线的事，写下来就不会忘。
验收标准要满足三个条件：具体（有页面、有动作、有数字）、可观察（结果看得见）、可重复（换一个人来检查，结论一样）。一个好用的句式是：在什么情况下，我做什么，应该看到什么。
| 模糊的写法 | 能验收的写法 |
|---|---|
| 网站要快 | 首页用生产构建、手机模式跑 Lighthouse，性能分连续 3 次都在 90 以上 |
| 分享要好看 | 把 /quiz/result/thai 发到聊天软件，卡片上有“泰风”“被保护感”和泰风配色 |
| 防止刷提问 | 同一 IP 10 分钟内第 4 次提交被拒绝，页面有提示，数据库里没有新增记录 |
| 出错要友好 | 访问 /abc 显示自定义 404 页，页面上有回首页的链接，状态码是 404 |
写验收标准时顺便想一想“怎么测”。能写成自动化测试的（比如 404 状态码、未登录跳转），交给 Playwright，以后每次 CI 都会替你检查；只能靠眼睛判断的（卡片好不好看、文案油不油腻），写进 DAY 71 的上线检查清单。这样每条标准都有“负责检查的人”。
为什么需要它？Claude Code 每次开新对话都像“第一天上班”，不记得昨天聊过什么。CLAUDE.md 放在项目根目录，Claude Code 每次开始会话都会自动读进来，官方文档把它叫作项目说明（project instructions）。它就像贴在工地门口的施工须知：技术栈是什么、哪些规矩不能破、做完怎么交活。
官方文档给了几条写法建议，今天照着做：每个 CLAUDE.md 尽量控制在 200 行以内，太长会占用上下文，Claude 反而执行得不稳定；写具体、能检查的规则，比如“后台每个 Server Action 开头都要检查登录”，而不是“注意安全”；规则之间不要互相矛盾。你可以在 Claude Code 里输入 /init 让它读项目后生成一份草稿，如果 CLAUDE.md 已经存在，它会提出修改建议而不是覆盖。以后想改可以用 /memory 打开编辑，用 /context 确认它确实被加载了。只属于你个人、不想提交到 Git 的偏好，可以写在 CLAUDE.local.md 里，并把它加进 .gitignore。
dongge-web/CLAUDE.md
# dongge-web 项目说明（给 Claude）
## 项目是什么
「三岁的东哥」个人 IP 官网。前台给粉丝看（主要是女性，多用手机），后台只有东哥一个管理员。
三个世界：gentleman 绅士（安全感）、street 街头（心动）、thai 泰风（被保护感）。
## 我是谁、怎么和我协作
- 我是编程初学者，正在学全栈。每次改动请用中文解释“改了什么、为什么这样改”。
- 有多种做法时，先列出选项和取舍，等我选择，不要直接动手。
- 一次只做一个 issue 的事，不要顺手改无关的文件。
- 改代码前先确认当前在功能分支上，不要在 main 上直接提交。
- 不要运行 git push 和 gh pr merge，这两步由我来做。
- 不确定的 API 写法，先查官方文档，不要凭记忆写。
## 技术栈（不要换成别的库，也不要新增依赖，除非我同意）
- Next.js（App Router）+ React + TypeScript
- Tailwind CSS v4（CSS 里写 @import "tailwindcss";，没有 tailwind.config.js）
- Prisma ORM + Neon PostgreSQL（新加坡区域）
- Better Auth（管理员登录）
- Zod（输入校验）
- Vercel Blob（图片）
- @anthropic-ai/sdk（文案助手）
- Recharts（看板图表）
- Vitest（单元测试）+ Playwright（端到端测试）
- GitHub Actions（CI）+ Vercel（部署）
## 目录结构
- app/ 页面和路由
- page.tsx 首页
- world/[slug]/ 三个世界详情页
- links/ 链接页
- quiz/ 测试小游戏
- ask/ 粉丝提问箱（actions.ts 是 Server Action）
- admin/ 后台：looks、questions、assistant、dashboard
- api/ Route Handlers：auth、assistant
- components/ 可复用组件
- lib/ prisma.ts、auth.ts、validations.ts 等工具
- prisma/schema.prisma 数据模型：World、Look、Question、Draft、统计表
- tests/ Playwright 测试；Vitest 测试和被测文件放在一起（*.test.ts）
- docs/ 需求文档、故障手册、复盘
## 常用命令
- npm run dev 本地开发，打开 http://localhost:3000
- npm run build 生产构建，提交前必须通过
- npm run lint 代码检查
- npx tsc --noEmit 类型检查
- npm test Vitest 单元测试
- npx playwright test 端到端测试
- npx prisma migrate dev --name 名称 改了 schema 后生成并应用迁移
- npx prisma generate 生成 Prisma Client（Prisma 7 起迁移后不会自动生成）
## 代码规范
- 默认写服务端组件；只有用到 state、事件或浏览器 API 时才加 "use client"，并尽量加在小组件上。
- 所有用户输入先用 lib/validations.ts 里的 Zod 规则校验，服务端必须再校验一次。
- 后台的每个 Server Action 和 Route Handler 开头都要检查登录状态。
- 只通过 lib/prisma.ts 导出的 prisma 访问数据库。
- 密钥只从 process.env 读取、只在服务端使用；不要写进代码、日志或注释。
- 组件文件用 PascalCase（LookCard.tsx），其他文件用 kebab-case（rate-limit.ts）。
- 新功能要有测试：纯函数写 Vitest，关键流程写 Playwright。
## 环境变量（值只在 .env 和 Vercel 后台，不要写进任何提交的文件）
DATABASE_URL、BETTER_AUTH_SECRET、BETTER_AUTH_URL、BLOB_READ_WRITE_TOKEN、ANTHROPIC_API_KEY
## 文案规则
默认文案和示例文案守住“说事情不说情话”：克制、具体、不油腻，不写土味情话。
## 一个任务怎样算完成
1. npm run lint、npx tsc --noEmit、npm test、npm run build 全部通过
2. 列出改动的文件和每处改动的原因
3. 告诉我怎么手动验证，对照 issue 里的验收标准逐条说明逐段解释：“项目是什么”让 Claude 写默认文案、示例数据时贴合三个世界，不会冒出 foo、bar。“我是谁、怎么和我协作”是最关键的一段：它让 Claude 每次都解释原因（你在学习），遇到选择先问你（你是指挥），不碰 push 和 merge（最后一道关卡在你手里）。“技术栈”一段防止它引入你没学过的新库。“目录结构”让它一上来就知道去哪找文件，省得每次重新摸索；这一段要和你项目的真实结构一致，下午用 ls 核对。“常用命令”里特意写了 Prisma 7 迁移后要手动 generate，这是新手常踩的坑。“代码规范”每条都能检查，DAY 70 做代码审查时，Claude 也会拿它当标准。“环境变量”只写名字，不写值。最后一段“怎样算完成”相当于交活标准，省得你每次都重复叮嘱。
CLAUDE.md 写给 Claude，README 写给人：几个月后的你、帮你看代码的朋友、将来可能合作的人。GitHub 仓库首页会自动显示 README，它是项目的门面。一份合格的 README 回答五个问题：这是什么、网址在哪、用了什么技术、怎么在本地跑起来、怎么部署。环境变量只写名字和用途，真正的值永远不出现。
dongge-web/README.md
# 三岁的东哥 · dongge-web
「三岁的东哥」个人 IP 官网：三个世界（绅士 / 街头 / 泰风）、链接页、测试小游戏、粉丝提问箱，
以及只给管理员用的内容工作台（looks 管理、提问审核、AI 文案助手、数据看板）。
线上地址：https://（DAY 69 绑定域名后填写）
## 技术栈
Next.js（App Router）· TypeScript · Tailwind CSS v4 · Prisma · Neon PostgreSQL ·
Better Auth · Zod · Vercel Blob · Claude API · Recharts · Vitest · Playwright · GitHub Actions · Vercel
## 本地运行
1. 安装 Node.js（LTS 版）
2. 克隆仓库并安装依赖
git clone https://github.com/你的用户名/dongge-web.git
cd dongge-web
npm install
3. 复制环境变量模板，填入自己的值（不要提交 .env）
cp .env.example .env
4. 生成 Prisma Client 并应用迁移
npx prisma generate
npx prisma migrate dev
5. 启动
npm run dev
打开 http://localhost:3000
## 环境变量
| 名称 | 用途 |
| DATABASE_URL | Neon 数据库连接串 |
| BETTER_AUTH_SECRET | 登录会话加密用的随机字符串 |
| BETTER_AUTH_URL | 网站地址，本地是 http://localhost:3000 |
| BLOB_READ_WRITE_TOKEN | Vercel Blob 上传图片 |
| ANTHROPIC_API_KEY | 文案助手调用 Claude API |
## 常用命令
npm run build / npm run lint / npm test / npx playwright test
## 部署
推送到 main 后由 Vercel 自动部署；改功能走分支 + Pull Request，CI 通过后再合并。这里的 .env.example 是一个只有变量名、没有值的模板文件，可以放心提交。别人拿到仓库后复制一份改名成 .env，自己填值。下午你会顺手把它建出来。
为什么要先出方案？改方案只要改几行字，改代码要改几十个文件。Plan 模式下，Claude 只读代码、运行查看类命令、写出计划，不修改源代码。在桌面 App 里，发送按钮旁边有一个权限模式选择器，选 Plan 就行；也可以按 Cmd + Shift + M 切换，或者直接在输入框里输入 /plan 加一句任务描述。
方案出来后，你要像监理一样审，问自己四个问题：有没有做“明确不做”里的事？每一步能不能验收？顺序对不对（影响大的、风险高的先做）？有没有引入新的库？有任何一条不满意，就直接告诉 Claude 改，改到你满意为止。
拆 issue 时还要注意“粒度”，也就是一张卡片装多少活。太大（比如“完成安全加固”）会让一次改动涉及十几个文件，你审不过来；太小（比如“给按钮改个颜色”）又会让卡片多到管不过来。一个简单的标准：一条 issue 的改动你能在半小时内读完 diff，并且能用两三条验收标准说清楚“做完的样子”。做不到就再拆，比如把“安全加固”拆成“提问箱限流”“文案助手限流”“404 和 500 页面”三条。每条 issue 对应一个分支、一个 Pull Request，出了问题也容易定位是哪一次改动带来的。
审好的方案要变成一张张待办卡片，这就是 GitHub issue。一条好 issue 包含：结果导向的标题、背景、要做什么、验收标准、不做什么。再给它贴上标签（label），方便分类筛选。以后开 Pull Request 时，在描述里写 Closes #12，PR 合并后 12 号 issue 会自动关闭，需求、代码、验收就串在了一起。
用命令行创建 issue 要用到 GitHub 官方的 gh 工具（DAY 53 做 Pull Request 时你已经登录过）。标签必须先存在，所以先建标签：
gh label create performance --color 1D76DB --description "速度与体积"这行的意思是：在当前仓库新建一个叫 performance 的标签，--color 是 6 位十六进制颜色（不带 #），--description 是说明文字。然后把 issue 正文先写进一个临时文件，比如：
dongge-web/issue-body.md（临时文件，用完删除）
## 背景
粉丝多从手机打开首页，现在 Lighthouse 性能分不到 90。
## 要做什么
- 页面图片改用 next/image
- 字体改用 next/font
- 检查每个 "use client" 能不能下移到更小的组件
## 验收标准
- [ ] 生产构建下，手机模式 Lighthouse 性能分连续 3 次都在 90 以上
- [ ] CLS 不超过 0.1
- [ ] npm run build 通过，CI 全绿
## 不做
- 不改页面设计，不换图片内容gh issue create \
--title "首页手机端 Lighthouse 性能分达到 90 以上" \
--label performance \
--body-file issue-body.md逐行解释：gh issue create 在当前目录对应的 GitHub 仓库里新建 issue；行尾的反斜杠 \ 表示命令没完、下一行接着写；--title 是标题；--label 是标签，可以写多次贴多个；--body-file 表示正文从文件读取，比把一大段文字塞进命令里更不容易出错。成功后终端会打印这个 issue 的网址。
gh issue list 查看所有打开的 issue，用 gh issue view 1 --web 在浏览器里打开 1 号 issue。同步项目，完整走一遍网站
打开终端，回到最新的 main 分支并启动项目：
cd ~/code/dongge-web
git switch main
git pull
npm run dev用浏览器的手机模拟模式和电脑模式，把每个页面都点一遍：首页、三个世界、链接页、测试小游戏（三种结果都做出来）、提问箱、后台每个页面。在本子上按三列记录：功能、现在的问题、想改成什么样。
新建文档分支，自己写需求文档
git switch -c docs/v1-requirements
mkdir -p docs
code docs/requirements.md照上午的模板，结合你上一步的清单，亲手写 docs/requirements.md。这一步不要让 Claude 代写：需求是你的判断，写的过程就是想清楚的过程。“明确不做”至少写 3 条，每条验收标准都用“在什么情况下，我做什么，应该看到什么”的句式检查一遍。
让 Claude 挑刺，只挑不改
在 Claude Code 里打开 dongge-web 项目，把“问 Claude”第 1 条提示词发给它。它会列出模糊、无法验收、互相矛盾的条目。你逐条判断：同意的自己改，不同意的写下理由。
生成 CLAUDE.md 草稿，再按规范改
在 Claude Code 输入框里输入 /init，让它读项目后生成一份 CLAUDE.md 草稿。然后在终端核对真实的目录结构：
ls app app/admin lib components
cat package.json对照上午的完整示例修改草稿：补上“我是谁、怎么和我协作”“技术栈（不要换库）”“环境变量只写名字”“文案规则”“一个任务怎样算完成”；目录结构和常用命令改成你项目里的真实情况（比如你的提问箱如果在 app/questions，就写 app/questions）；删掉 Claude 看代码就能知道的冗长描述。
wc -l CLAUDE.md，行数在 200 以内；里面没有任何密钥的值。确认 CLAUDE.md 生效
在 Claude Code 里开一个新对话，输入 /context，在 Memory files 一栏找到 CLAUDE.md。再问它：“请用三句话说出这个项目里你必须遵守的协作规则。”
写 README 和 .env.example，检查 .gitignore
按上午示例写 README.md。再新建 .env.example，只写变量名、等号后面留空：
dongge-web/.env.example
DATABASE_URL=
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=http://localhost:3000
BLOB_READ_WRITE_TOKEN=
ANTHROPIC_API_KEY=然后检查忽略规则：
cat .gitignore
git status确认 .gitignore 里有 .env* 这类规则。注意：如果写的是 .env*，它也会把 .env.example 忽略掉，需要在下面加一行 !.env.example 表示“这个例外，要提交”。再加一行 CLAUDE.local.md。
git status 里能看到 README.md、CLAUDE.md、.env.example，看不到 .env。提交并开 Pull Request
git add docs/requirements.md CLAUDE.md README.md .env.example .gitignore
git commit -m "docs: 正式版需求文档、CLAUDE.md 和 README"
git push -u origin docs/v1-requirements
gh pr create --fillgh pr create --fill 会用提交信息自动填 PR 标题和描述。打开终端打印出来的 PR 网址，自己把改动从头读一遍，等 CI 通过后合并（网页上点 Merge，或运行 gh pr merge --squash --delete-branch）。最后回到 main：
git switch main
git pull切到 Plan 模式出改进方案
在桌面 App 发送按钮旁的模式选择器里选 Plan（或按 Cmd + Shift + M）。把“问 Claude”第 2 条提示词发给它。
git status 是干净的）。像监理一样审方案
用上午的四个问题逐条过：有没有“明确不做”的事、能不能验收、顺序对不对、有没有新库。把要删、要改、要合并的地方直接告诉 Claude，让它出修订版。最终列表控制在 8 到 12 条 issue，把它复制保存到本子或备忘录里。
创建标签
先确认 gh 登录正常，再一次建好 6 个标签：
gh auth status
gh label create performance --color 1D76DB --description "速度与体积"
gh label create seo --color 0E8A16 --description "标题、描述、分享卡片"
gh label create security --color B60205 --description "限流、校验、错误页"
gh label create ops --color 5319E7 --description "备份、日志、域名"
gh label create test --color FBCA04 --description "测试与 CI"
gh label create launch --color D93F0B --description "上线检查与发布"gh label list 能看到这 6 个标签。亲手创建第一条 issue
在项目根目录新建 issue-body.md，把上午的性能 issue 正文粘进去（按你的实际情况改数字），然后：
gh issue create \
--title "首页手机端 Lighthouse 性能分达到 90 以上" \
--label performance \
--body-file issue-body.md
rm issue-body.md
gh issue listgh issue list 里出现了这条 issue，用 gh issue view 编号 --web 能在浏览器里看到完整正文和标签。让 Claude 创建其余 issue，然后填回里程碑
把模式切回 Manual（每一步都会先问你），把“问 Claude”第 3 条提示词和你审定的列表一起发给它。每条 gh issue create 命令弹出确认时，先读一遍标题和标签再允许。全部建完后，把 issue 编号填进 docs/requirements.md 的里程碑表格，下次提交时一起带上。明天从性能那条 issue 开始：学会看 Lighthouse 报告，把首页分数跑到 90 以上。
gh issue list --limit 30 显示 8 到 12 条打开的 issue，每条都有标签。gh label create 建好，名字大小写必须一致。用 gh label list 看已有标签。git status 和 git diff 看改了什么，确认都不要后用 git restore . 撤销未提交的改动。.gitignore 里的 .env* 把它也忽略了。加一行 !.env.example，再 git status 确认。正式版必须有的 3 个功能，和明确不做的 3 个功能分别是什么？
答案因人而异，关键是每条都有理由。示例：必须有的是测试小游戏和专属分享图（最容易被转发，带来新访客）、提问箱加后台审核（和粉丝互动，又不会让不合适的内容直接上墙）、链接页（平台简介里只能放一个链接，它是所有平台的入口）。明确不做的是粉丝注册登录（要保存更多个人信息，维护和安全成本高）、多语言（现在精力不够，先把中文版做好）、手机 App（网页在手机上已经能用，App 还要审核和维护）。
CLAUDE.md 和 README 分别写给谁？各举两条只应该出现在其中一个里的内容。
CLAUDE.md 写给 Claude，每次会话自动加载，内容是它干活要遵守的规矩，比如“我是初学者，每次改动请解释原因”“不要运行 git push 和合并”。README 写给人，是仓库的门面，比如“网站是做什么的、线上地址”“从克隆到本地运行的步骤”。两者都可以列常用命令，但都不能出现密钥的值。
把“提问箱要防刷”改写成两条能验收的标准，并说出分别用什么方法检查。
第一条：同一 IP 在 10 分钟内提交第 4 条提问时，页面显示“提交太频繁，请稍后再试”，数据库里没有新增记录。检查方法：手动连续提交 4 次，再在 Neon 的 SQL 编辑器里查 Question 表的条数。第二条：提问内容超过 300 字时，服务端拒绝保存并返回错误提示。检查方法：写一个 Vitest 测试，用 301 个字调用 Zod 校验规则，断言校验失败。
next/image 正确显示 Vercel Blob 里的照片：配置 remotePatterns，用 fill 和 sizes，只让首屏图片立即加载。next/font 自托管英文字体，并解释为什么正文中文用系统字体更快。昨天你在需求文档里写下“首页手机端 Lighthouse 性能分 90 以上”。为什么这一条排在最前面？想一想粉丝是怎么来的：她在小红书刷到你的视频，点进主页，再点简介里的链接。这时她用的是手机、可能是地铁里的 4G、心里还惦记着刚才的视频。页面三秒还是白的，她就划走了，你前面拍视频花的功夫就浪费了。
Lighthouse 是 Chrome 自带的网页“体检工具”。它模拟一台中等性能的手机、在较慢的网络下打开你的页面，然后给出四类分数：性能（Performance）、无障碍（Accessibility）、最佳实践（Best Practices）、搜索引擎优化（SEO），新版还增加了一类面向 AI 浏览代理的检查。每类满分 100：0 到 49 是红色（差），50 到 89 是橙色（需要改进），90 到 100 是绿色（好）。今天主攻性能分，其他几类顺手看一眼。
它和体检一样，不只给一个总分，还会列出“哪里有问题、建议怎么改”。你的任务不是背下所有建议，而是学会读报告、找到最拖分的一两项，改完再测，用数字验证改动有没有用。
性能分是五个指标的加权平均。想象你走进一家餐厅：
| 指标 | 在量什么 | 餐厅比喻 | 权重 |
|---|---|---|---|
| FCP（首次内容绘制） | 页面第一次出现任何文字或图片的时间 | 坐下后第一杯水端上来 | 10% |
| Speed Index（速度指数） | 页面内容整体显示出来有多快 | 桌子多快被摆满 | 10% |
| LCP（最大内容绘制） | 屏幕上最大的那块内容（常常是大图或大标题）显示出来的时间 | 主菜什么时候上 | 25% |
| TBT（总阻塞时间） | 加载期间主线程被 JavaScript 占住、点了没反应的总时长 | 服务员忙着别的事，你招手没人理 | 30% |
| CLS（累计布局偏移） | 内容加载时页面跳来跳去的程度 | 刚要夹菜，盘子被挪走了 | 25% |
表里的权重来自 Lighthouse 官方文档目前列出的数字，以后版本可能调整，以官方为准。从权重能看出重点：LCP、TBT、CLS 三项加起来占 80%。对你的网站来说，LCP 通常卡在照片太大，CLS 通常卡在图片和字体加载时把内容挤动，TBT 卡在发给浏览器的 JavaScript 太多。今天的三个主要动作（图片、字体、JavaScript）就是冲着这三项去的。
第一条规则：测生产构建，不测开发模式。npm run dev 为了方便调试，不压缩代码、还带着热更新脚本，分数会低得离谱，没有参考价值。要么在本地运行 npm run build 再 npm run start，要么直接测 Vercel 上的线上网址。
第二条规则：用无痕窗口。浏览器扩展（翻译、广告拦截、密码管理）会往页面里塞代码，拖慢结果。无痕窗口默认不运行扩展，官方文档也建议这样做。
具体操作：按 Cmd + Shift + N 打开无痕窗口，访问要测的网址；按 Cmd + Option + I 打开开发者工具，在顶部标签里找到 Lighthouse（标签多时可能藏在 >> 里）。模式（Mode）选 Navigation，设备（Device）选 Mobile，类别全选，点击 Analyze page load，等半分钟左右。界面文字会随 Chrome 版本和语言略有不同，找相近的选项即可。
读报告按这个顺序：先看总分和五个指标，哪个是红的或橙的；再往下找“Largest Contentful Paint element”（中文界面叫“最大内容绘制元素”），它会直接告诉你 LCP 是哪张图或哪段文字；最后看下方的诊断建议（不同版本叫 Diagnostics 或 Insights），每条后面常常标着预计能省多少时间或多少体积，从省得最多的开始改。
还有一个线上工具 PageSpeed Insights，输入网址就能跑同样的 Lighthouse 测试，它在 Google 的服务器上测，适合测已经上线的网址，和本地结果对照着看。
为什么图片最拖分？你在 DAY 49 上传的 look 照片是手机直出的，一张可能有 3 到 5 MB、宽 4000 像素，而手机屏幕上只需要宽 400 像素左右的版本。浏览器下载了十倍的数据，LCP 自然慢。另外，普通的 <img> 在图片下载完之前不知道它有多高，图片一出来就把下面的文字往下推，这就是 CLS。
next/image 帮你做了四件事：按屏幕尺寸自动生成多个大小的版本，浏览器只下载合适的那个；自动转换成体积更小的 WebP 格式（也可以在配置里开启 AVIF）；默认懒加载，也就是图片快滚动到眼前才开始下载；要求你给出宽高或用 fill 填满一个定好尺寸的容器，提前把位置占住，页面就不会跳。
你的照片存在 Vercel Blob，网址是 https://一串字符.public.blob.vercel-storage.com/... 这种外部地址。为了安全，Next.js 默认不处理外部图片，必须在配置里明确放行哪个域名，否则任何人都能借你的服务器处理他的图片。DAY 49 如果已经配过，今天检查一下写得够不够严格：
dongge-web/next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
images: {
remotePatterns: [
{
protocol: "https",
hostname: "*.public.blob.vercel-storage.com",
pathname: "/**",
},
],
},
};
export default nextConfig;逐行解释：images.remotePatterns 是一张“外部图片白名单”；protocol: "https" 只允许加密地址；hostname 里的 * 匹配一段子域名，也就是你的 Blob 存储编号；pathname: "/**" 允许这个域名下的所有路径。不在名单上的图片地址会直接返回 400 错误。改了 next.config.ts 要重启开发服务器才生效。
接下来是 look 卡片。首页和世界页用网格排列卡片（手机一列、平板两列、电脑三列），图片宽度随屏幕变化，这种情况用 fill 最方便：
dongge-web/components/LookCard.tsx
import Image from "next/image";
type LookCardProps = {
title: string;
description: string;
imageUrl: string | null;
worldName: string;
aboveTheFold?: boolean;
};
export default function LookCard({
title,
description,
imageUrl,
worldName,
aboveTheFold = false,
}: LookCardProps) {
return (
<article className="overflow-hidden rounded-2xl bg-white shadow-sm">
{imageUrl ? (
<div className="relative aspect-[3/4] w-full">
<Image
src={imageUrl}
alt={`${worldName}造型：${title}`}
fill
sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
className="object-cover"
loading={aboveTheFold ? "eager" : "lazy"}
fetchPriority={aboveTheFold ? "high" : "auto"}
/>
</div>
) : (
<div className="flex aspect-[3/4] items-center justify-center bg-neutral-100 text-neutral-400">
暂无照片
</div>
)}
<div className="p-4">
<p className="text-sm text-neutral-500">{worldName}</p>
<h3 className="mt-1 text-lg font-semibold">{title}</h3>
<p className="mt-2 text-sm text-neutral-600">{description}</p>
</div>
</article>
);
}逐段解释：外层 div 的 relative aspect-[3/4] w-full 很关键。fill 模式下图片会铺满离它最近的定位父元素，所以父元素必须是 relative；aspect-[3/4] 让容器按 3:4 的比例提前占好高度，图片没下载完位置也已经留出来，CLS 就降下来了。alt 写成“街头造型：某某”，读屏软件和图片加载失败时都能看到有意义的文字。sizes 告诉浏览器：屏幕宽 1024 像素以上时图片约占三分之一屏宽，768 以上约占一半，更窄时占满全宽，浏览器据此挑最合适的尺寸下载；它要和你的网格列数对应。object-cover 让照片裁切填满而不变形。
最后两行控制加载时机。默认 loading="lazy"，只有快滚到眼前才下载，这对首屏以下的卡片正合适。但首屏第一张图如果也懒加载，就会拖慢 LCP，所以用 aboveTheFold 这个参数，让排在最前面的一两张改成 loading="eager"（立即加载）加 fetchPriority="high"（优先下载）。使用时写 aboveTheFold={index === 0} 就行。
preload 属性，适合“首屏只有一张大图、而且它一定是 LCP”的情况，比如首页顶部的一张主视觉照片。Next.js 16 起旧的 priority 属性已弃用、由 preload 代替；如果你的项目版本低于 16，还是写 priority。用 npx next --version 查看版本，以官方文档为准。字体文件也要下载。如果你在 CSS 里用 @import url(https://fonts.googleapis.com/...) 或在页面头部用 <link> 引入 Google Fonts，浏览器要先连到 Google 的服务器下载 CSS，再下载字体文件，这两步都会拖慢首屏；字体到了以后，文字从系统字体换成新字体，宽度变了，页面会跳一下，又伤 CLS。对中国大陆的访客还有一个额外问题：连 Google 的服务器可能很慢甚至连不上。
next/font 解决了这些问题：构建时就把字体文件下载下来，和你的网站放在同一个域名下提供，浏览器不再向 Google 发请求；它还会自动计算一个尺寸接近的备用字体，字体切换时几乎不跳。
中文字体要特别注意：一套中文字体有上万个字，文件动辄几 MB。所以正文中文建议直接用系统字体（苹果设备上是苹方，安卓上一般是思源黑体或厂商字体），Tailwind 默认的 font-sans 就会用到它们，零下载。只给英文大标题（比如 DONGGE、三个世界的英文名）用一款网络字体，体积只有几十 KB。
dongge-web/app/layout.tsx（只看和字体有关的部分）
import { Oswald } from "next/font/google";
import "./globals.css";
const oswald = Oswald({
subsets: ["latin"],
variable: "--font-oswald",
display: "swap",
});
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="zh-CN" className={oswald.variable}>
<body className="antialiased">{children}</body>
</html>
);
}dongge-web/app/globals.css（开头部分）
@import "tailwindcss";
@theme inline {
--font-display: var(--font-oswald);
}逐行解释：Oswald(...) 在构建时下载这款字体；subsets: ["latin"] 只要拉丁字母部分，体积最小；variable: "--font-oswald" 让它生成一个 CSS 变量；display: "swap" 表示字体没到之前先用备用字体显示文字，不让文字空白。className={oswald.variable} 把这个变量挂到 <html> 上，整个页面都能用。在 globals.css 里，Tailwind v4 的 @theme inline 把它登记成一个叫 display 的字体，之后写 className="font-display" 就能用。注意 --font-display 和 --font-oswald 名字不能一样，否则变量会引用自己。你的 layout 里可能还有导航、页脚和 metadata，保留它们，只改字体相关的这几处。
TBT 占 30%，它量的是 JavaScript 把浏览器“占住”的时间。DAY 39 学过：服务端组件在服务器上渲染成 HTML，不往浏览器发它自己的 JavaScript；只有带 "use client" 的组件和它导入的所有东西才会被打包发给浏览器。所以减少 TBT 最有效的办法，是检查每个 "use client" 放得对不对。
常见的问题是“为了一个按钮，把整页变成客户端组件”。比如首页顶部有个风格切换按钮要用 useState，于是在 app/page.tsx 第一行写了 "use client"，结果整页的卡片、文案、图片组件都被打包发给了浏览器。正确的形状是：页面保持服务端组件，负责查数据库和排版；只把风格切换按钮单独做成一个小的客户端组件。
dongge-web/app/page.tsx（示意结构）
import LookCard from "@/components/LookCard";
import StyleSwitcher from "@/components/StyleSwitcher";
import { prisma } from "@/lib/prisma";
export default async function HomePage() {
const looks = await prisma.look.findMany({
where: { published: true },
include: { world: true },
orderBy: { createdAt: "desc" },
take: 6,
});
return (
<main className="mx-auto max-w-5xl px-4 py-10">
<h1 className="font-display text-5xl uppercase">Dongge</h1>
<StyleSwitcher />
<section className="mt-8 grid gap-6 md:grid-cols-2 lg:grid-cols-3">
{looks.map((look, index) => (
<LookCard
key={look.id}
title={look.title}
description={look.description}
imageUrl={look.imageUrl}
worldName={look.world.name}
aboveTheFold={index === 0}
/>
))}
</section>
</main>
);
}这个文件第一行没有 "use client"，它在服务器上直接查数据库。只有 StyleSwitcher 文件顶部写了 "use client"，浏览器只需要下载这一个小组件的代码。你的首页结构可能和示意不同，看懂“页面在服务端、交互在小组件”这个形状即可。
还有一种办法是“晚一点发”：有些客户端组件不是一打开页面就需要，比如点了“给东哥提问”才展开的表单。可以用 next/dynamic 等用户点击后再下载它的代码：
dongge-web/components/AskPanel.tsx
"use client";
import { useState } from "react";
import dynamic from "next/dynamic";
const AskForm = dynamic(() => import("@/components/AskForm"), {
loading: () => <p className="text-sm text-neutral-500">加载中…</p>,
});
export default function AskPanel() {
const [open, setOpen] = useState(false);
return (
<div>
<button
type="button"
onClick={() => setOpen(true)}
className="rounded-full bg-neutral-900 px-5 py-3 text-white"
>
给东哥提问
</button>
{open && <AskForm />}
</div>
);
}逐行解释：dynamic(() => import(...)) 把 AskForm 拆成一个单独的代码包；loading 是下载期间显示的占位内容；{open && <AskForm />} 只有点了按钮、open 变成 true 时才渲染表单，这时浏览器才去下载它。官方文档提醒两点：next/dynamic 的拆包要写在客户端组件里才有效，所以这个文件顶部有 "use client"；ssr: false 选项也只能在客户端组件里用。这是锦上添花的手段，先把 "use client" 放对位置，报告里还提示“未使用的 JavaScript”太多时再考虑它。明天要给每个页面配分享卡片，性能打好底，分享出去的链接打开才快。
找到性能 issue，新建分支
cd ~/code/dongge-web
git switch main
git pull
gh issue list --label performance
git switch -c perf/home-lighthouse记下这条 issue 的编号，今天所有改动都围绕它的验收标准。
生产构建，跑出基线分数
npm run build
npm run start按 Cmd + Shift + N 打开无痕窗口，访问 http://localhost:3000，打开开发者工具的 Lighthouse，选 Navigation、Mobile，跑 3 次。新建 docs/perf-log.md 记录：
dongge-web/docs/perf-log.md
# 首页性能记录（手机模式，生产构建，每次跑 3 次）
| 日期 | 改动 | 性能分（3 次） | LCP | TBT | CLS |
| 2026-xx-xx | 基线（未改动） | | | | |读报告，找到拖分的元凶
在报告里找到“最大内容绘制元素”，看它是哪张图或哪段文字；再把诊断建议前 5 条连同五个指标复制下来，用“问 Claude”第 1 条提示词请它按影响大小排序并对应到文件。你自己判断先改哪一项，写在记录表下面。
盘点页面里的图片
grep -rn "<img" app components
ls -lh public第一条找出还在用普通 <img> 的地方，第二条看 public 文件夹里的图片有多大。再在后台随便打开一张 look 照片，右键“在新标签页中打开图片”，看看原图尺寸。
下任务：图片改用 next/image
把“问 Claude”第 2 条提示词发给 Claude（模式用 Manual 或 Accept edits）。它改完后，点开改动行数打开 diff，按这张清单逐项审查：
Image 都有有意义的 alt，不是“image”或空字符串（纯装饰图除外）。fill 的，父元素有 relative 和固定比例或高度。sizes 和网格列数对得上。remotePatterns 只放行 Blob 的域名，没有出现 unoptimized。npm run dev，首页、世界页、后台 looks 列表的照片都正常显示，终端没有 hostname 相关报错。检查字体的加载方式
grep -rn "fonts.googleapis" app components
grep -rn "next/font" app如果第一条有结果，说明还在从 Google 服务器加载字体，照上午的写法改成 next/font；如果已经在用 next/font，检查是不是加载了中文网络字体（比如 Noto Sans SC），有的话改回系统字体，只给英文标题保留一款网络字体。改完在页面上确认标题字体没变样。
审计每一个 "use client"
grep -rlE "[\"']use client[\"']" app components这条命令列出所有写了 "use client" 的文件（单引号双引号都算）。把“问 Claude”第 3 条提示词发给它，逐个听它解释。只要有一个整页都是客户端组件、其实只有一个小按钮需要交互的，就让它按“页面在服务端、交互在小组件”的形状改掉，你来审 diff。
app/page.tsx 第一行没有 "use client"。重新构建，再测 3 次
先按 Ctrl + C 停掉之前的服务，再：
npm run build
npm run start在新的无痕窗口里再跑 3 次 Lighthouse，把结果作为新的一行记进 docs/perf-log.md，“改动”一栏写清楚这次改了什么。如果还没到 90，回到第 3 步，看下一条最拖分的诊断，每次只改一件事再测，这样才知道是哪项改动起的作用。
跑检查和测试
npm run lint
npx tsc --noEmit
npm test
npx playwright test图片换了组件，Playwright 里如果有按 img 标签找元素的测试可能会受影响，读懂报错再决定是改测试还是改代码。
提交并开 PR，关联 issue
git add -A
git status
git commit -m "perf: 首页图片、字体和客户端组件优化"
git push -u origin perf/home-lighthouse
gh pr create --title "perf: 首页 Lighthouse 性能分达到 90 以上" --body "Closes #编号"把 #编号 换成第 1 步记下的 issue 编号。git add -A 之后先看 git status，确认没有把 .env 之类的文件加进去。等 CI 通过，在手机上打开预览网址看一遍照片和字体。
合并后测线上网址
合并 PR，等 Vercel 部署完成，在无痕窗口里对线上网址跑 3 次 Lighthouse，再到 PageSpeed Insights 输入网址跑一次，两边结果都记进表格。
gh issue view 编号 显示这条 issue 已经是 Closed 状态。回答今天的核心问题
看着 docs/perf-log.md，写一句话：哪一项改动让分数提高得最多，它改善的是哪个指标，为什么。这份记录表也要提交（可以和明天的改动一起）。明天给每个页面配标题、描述和分享图，让测试结果能生成专属的分享卡片。
npm run dev 下测的。开发模式不压缩代码、带调试脚本，必须用 npm run build 加 npm run start，或者直接测线上网址。remotePatterns，或者改了 next.config.ts 没重启开发服务器。relative，或者父元素没有高度。给父元素加 relative 和 aspect-[3/4] 这类比例类名。哪一项改动让分数提高得最多？
答案要来自你自己的 docs/perf-log.md，而不是猜。常见的情况是：把 look 照片换成 next/image 并让首屏第一张立即加载，LCP 从四五秒降到两秒多，分数提高最多，因为 LCP 权重 25%，而原图体积是网页里最大的一块；其次是给图片容器定好比例，CLS 明显下降。能回答这个问题的前提是每次只改一件事再测，所以记录表里每一行只对应一个改动。
为什么 next/image 要求写 width 和 height，或者用 fill 放进一个定好尺寸的容器？不这样做会影响哪个指标？
因为浏览器在图片下载完之前不知道它有多高。提前知道尺寸，就能先把位置占住；不知道的话，图片一出现就会把下面的内容往下推，页面跳动，影响的是 CLS（累计布局偏移），它占性能分的 25%。用户的感受是“正要点按钮，按钮跑了”。
首页有 6 张 look 卡片，为什么只让第一张（或首屏的一两张）立即加载，其余保持懒加载？
首屏的图片用户一打开就能看到，往往就是 LCP 元素，懒加载会让它晚开始下载，拖慢 LCP，所以要立即、优先加载。首屏以下的图片用户不一定会滚到，一开始就全部下载会和首屏图片抢网络，反而让首屏更慢，还浪费用户流量。如果把 6 张都设成优先，就等于没有优先。
metadataBase、标题模板和共用的 Open Graph 信息，并用 metadata 和 generateMetadata 给每个页面写标题和描述。opengraph-image.tsx 和 ImageResponse 生成全站分享图，以及三个测试结果各自的专属分享图，中文正确显示。sitemap.ts 和 robots.ts，并在浏览器和终端里验证它们。昨天把首页跑到了 90 分，今天让链接“被分享时好看”。你一定见过：把一个网址发给朋友，聊天框里会自动出现一张卡片，有标题、一句描述和一张图。这张卡片不是聊天软件凭空做的，过程是这样的：你发出网址，聊天软件的服务器派一个“机器人”去访问这个网址，只读 HTML 里 <head> 部分的几个标签，然后按标签内容拼出卡片。
它读的标签来自一套叫 Open Graph（开放图谱）的约定，最早由 Facebook 提出，现在大多数平台都认：
<meta property="og:title" content="我的测试结果：街头" />
<meta property="og:description" content="心动。你喜欢有点意外的日常。" />
<meta property="og:image" content="https://你的网址/quiz/result/street/opengraph-image?..." />
<meta property="og:site_name" content="三岁的东哥" />要记住两个关键点。第一，这个机器人一般不运行 JavaScript，只看服务器返回的 HTML，所以这些标签必须由服务器生成，靠浏览器里的 React 代码加上去是没用的。第二，og:image 必须是完整网址（带 https 和域名），因为机器人是在别人的服务器上访问你，相对路径它不知道从哪儿找。
在 Next.js 里你不用手写这些标签。在页面或布局里导出一个 metadata 对象，或者一个 generateMetadata 函数，Next.js 就会在服务器上生成对应的 <head> 标签。官方文档特别说明：这两种写法只能用在服务端组件里。如果某个页面文件第一行是 "use client"，就要把交互部分拆成单独的客户端组件，页面本身保持服务端组件，DAY 39 你已经这样拆过测试小游戏。
先建一个小文件，把网站地址、名字、默认描述集中放在一起。以后换域名（DAY 69）只改这一处，页面元信息、sitemap、robots 都会跟着变。
dongge-web/lib/site.ts
export const SITE_URL = "https://dongge-web.vercel.app";
export const SITE_NAME = "三岁的东哥";
export const SITE_DESCRIPTION =
"在外面是绅士、拳手、潮男，在你面前三岁。三个世界、一个小测试，还有给东哥的提问箱。";
export const ogDefaults = {
siteName: SITE_NAME,
locale: "zh_CN",
type: "website" as const,
};SITE_URL 换成你在 Vercel 上的真实网址。ogDefaults 是每个页面都一样的 Open Graph 信息：网站名、语言地区、类型。as const 让 TypeScript 把 "website" 当成固定的字面量类型，而不是普通字符串，这样才符合 Next.js 对 type 字段的类型要求。
dongge-web/app/layout.tsx（metadata 部分）
import type { Metadata } from "next";
import { SITE_URL, SITE_NAME, SITE_DESCRIPTION, ogDefaults } from "@/lib/site";
export const metadata: Metadata = {
metadataBase: new URL(SITE_URL),
title: {
default: SITE_NAME,
template: `%s | ${SITE_NAME}`,
},
description: SITE_DESCRIPTION,
openGraph: {
...ogDefaults,
},
twitter: {
card: "summary_large_image",
},
};逐行解释：metadataBase 是所有需要完整网址的字段的“前缀”，有了它，图片地址写相对路径 Next.js 也会自动补全成完整网址；官方文档说明，用了相对路径却没设 metadataBase 会直接构建报错。title.template 里的 %s 会被子页面的标题替换，比如链接页写 title: "链接"，最终标题就是“链接 | 三岁的东哥”；title.default 是子页面没写标题时用的默认值，写模板时必须同时写它。注意模板只作用于子页面，和布局同级的首页 app/page.tsx 不写标题，就用默认的“三岁的东哥”。twitter.card 设成大图卡片样式。
这里有一条容易踩的规则，官方文档叫“浅合并”：父布局和子页面都导出 metadata 时，同名的顶层字段由子页面整个替换。也就是说，子页面一旦写了 openGraph，根布局里的 openGraph 就整个作废，siteName、locale 都会丢。所以今天的做法是：普通页面只写 title 和 description，Open Graph 信息从根布局继承（聊天软件找不到 og:title 时，一般会退回读取页面的 <title>）；真的需要自己的 openGraph 时，用 ...ogDefaults 把共用信息展开进去，官方文档推荐的也是这种“抽成共享变量”的写法。
内容固定的页面，直接导出 metadata：
dongge-web/app/links/page.tsx（顶部新增）
import type { Metadata } from "next";
export const metadata: Metadata = {
title: "链接",
description: "东哥在小红书、TikTok、Facebook、Instagram 的主页入口。",
};三个世界的详情页内容来自数据库，标题要跟着 slug 变，就用 generateMetadata。页面本身也要查同一个世界，为了不查两次数据库，用 React 的 cache 把查询函数包起来，同一次请求里第二次调用会直接拿到第一次的结果：
dongge-web/lib/worlds.ts
import { cache } from "react";
import { prisma } from "@/lib/prisma";
export const getWorldBySlug = cache(async (slug: string) => {
return prisma.world.findUnique({ where: { slug } });
});dongge-web/app/world/[slug]/page.tsx（新增 generateMetadata）
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { getWorldBySlug } from "@/lib/worlds";
type Props = { params: Promise<{ slug: string }> };
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { slug } = await params;
const world = await getWorldBySlug(slug);
if (!world) {
return { title: "没有这个世界" };
}
return {
title: `${world.name}的世界`,
description: `${world.name}：给你${world.feeling}。看看东哥在这个世界里的穿搭和日常。`,
};
}
export default async function WorldPage({ params }: Props) {
const { slug } = await params;
const world = await getWorldBySlug(slug);
if (!world) notFound();
// 下面保留你原来的页面内容
return <main>{world.name}</main>;
}逐行解释：params 在新版 Next.js 里是一个 Promise，要先 await 才能拿到 slug。findUnique 要求 slug 在 schema 里标了 @unique，如果你的 schema 没有标，改用 findFirst。找不到世界时，metadata 返回一个简单标题，页面调用 notFound() 显示 404 页（明天会把 404 页做好看）。页面函数里的返回内容只是占位，保留你原来的代码，只加上查询和 notFound() 的判断。
分享图可以放一张做好的图片文件，但测试结果有三种，每种配色和文字不同，用代码生成更省事。Next.js 的约定是：在某个路由文件夹里放一个 opengraph-image.tsx，默认导出一个返回图片的函数，Next.js 就会自动生成图片地址，并把 og:image 等标签加到这个路由的页面上。放在 app/ 根目录的，作用于全站；放在更深的文件夹里的，优先级更高，会覆盖上层的。
生成图片用的是 next/og 里的 ImageResponse：你用 JSX 写一个“页面”，它先转成 SVG，再转成 PNG 图片。它不是真正的浏览器，所以有几条限制，官方文档写得很清楚：样式只能写在 style 属性里，不能用 Tailwind 类名；布局只支持 flexbox 和绝对定位，不支持 grid；一个元素里如果有多个子元素，必须明确写 display: "flex"；字体只支持 ttf、otf、woff 格式。推荐尺寸是 1200 × 630 像素。
中文是今天最大的坑。一套完整的中文字体有好几 MB，直接放进项目太大。Vercel 官方示例给了一个办法：向 Google Fonts 请求字体时带上 text 参数，只下载图片里真正用到的那几十个字，体积只有几十 KB。把它写成一个工具函数：
dongge-web/lib/og-font.ts
export async function loadGoogleFont(font: string, text: string): Promise<ArrayBuffer> {
const url = `https://fonts.googleapis.com/css2?family=${font}&text=${encodeURIComponent(text)}`;
const css = await (await fetch(url)).text();
const resource = css.match(/src: url\((.+)\) format\('(opentype|truetype)'\)/);
if (resource) {
const response = await fetch(resource[1]);
if (response.status === 200) {
return await response.arrayBuffer();
}
}
throw new Error("分享图字体加载失败");
}逐行解释：第一次 fetch 请求的是一段 CSS，text= 后面是图片里要用的所有文字（encodeURIComponent 把中文转成网址能用的格式）；Google 返回的 CSS 里有字体文件的地址，用正则表达式 match 把它抠出来；第二次 fetch 下载字体文件本身，转成 ArrayBuffer（一段二进制数据）交给 ImageResponse。任何一步失败就抛出错误，构建时你会在终端看到。这个请求发生在构建或服务器上，访客的浏览器不会连 Google。
dongge-web/app/opengraph-image.tsx（全站默认分享图）
import { ImageResponse } from "next/og";
import { loadGoogleFont } from "@/lib/og-font";
export const alt = "三岁的东哥";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";
export default async function Image() {
const title = "三岁的东哥";
const subtitle = "在外面是绅士、拳手、潮男，在你面前三岁";
const worlds = "绅士 · 街头 · 泰风";
const font = await loadGoogleFont("Noto+Sans+SC:wght@700", title + subtitle + worlds);
return new ImageResponse(
(
<div
style={{
width: "100%",
height: "100%",
display: "flex",
flexDirection: "column",
alignItems: "center",
justifyContent: "center",
background: "#111111",
color: "#ffffff",
fontFamily: "Noto Sans SC",
}}
>
<div style={{ fontSize: 110 }}>{title}</div>
<div style={{ fontSize: 36, marginTop: 24, color: "#d4d4d4" }}>{subtitle}</div>
<div style={{ fontSize: 30, marginTop: 48, color: "#ff5a1f" }}>{worlds}</div>
</div>
),
{
...size,
fonts: [{ name: "Noto Sans SC", data: font, style: "normal", weight: 700 }],
}
);
}逐段解释：导出的 alt、size、contentType 会变成 og:image:alt、宽高和图片类型标签。loadGoogleFont 的第二个参数是图片里出现的全部文字，少一个字，那个字就会显示成方块。最外层 div 有三个子元素，所以写了 display: "flex"，用 flexDirection: "column" 竖着排。fonts 里的 name 要和 fontFamily 一致。这张图不依赖请求数据，构建时生成一次就缓存起来。
现在测试结果只存在于浏览器的 state 里，没有自己的网址。聊天软件的机器人只认网址，所以要给每种结果一个独立页面：/quiz/result/gentleman、/quiz/result/street、/quiz/result/thai。粉丝做完测试点“分享我的结果”，跳到这个网址，再发给朋友，卡片上就是她的结果。先把三种结果的文案和配色集中放好：
dongge-web/lib/quiz-results.ts
export type WorldSlug = "gentleman" | "street" | "thai";
export type QuizResult = {
slug: WorldSlug;
name: string;
feeling: string;
line: string;
background: string;
accent: string;
};
export const QUIZ_RESULTS: Record<WorldSlug, QuizResult> = {
gentleman: {
slug: "gentleman",
name: "绅士",
feeling: "安全感",
line: "你看重靠谱：约好的时间准时到，答应的事有下文。",
background: "#1f3a2e",
accent: "#d4b483",
},
street: {
slug: "street",
name: "街头",
feeling: "心动",
line: "你喜欢有点意外的日常：周末去滑板场，摔了就笑着再来一次。",
background: "#111111",
accent: "#ff5a1f",
},
thai: {
slug: "thai",
name: "泰风",
feeling: "被保护感",
line: "你需要有人站在你这边：遇到事先挡在前面，再陪你把事情理清楚。",
background: "#7a1020",
accent: "#ffd23f",
},
};
const SLUGS: WorldSlug[] = ["gentleman", "street", "thai"];
export function isWorldSlug(value: string): value is WorldSlug {
return (SLUGS as string[]).includes(value);
}
export function getQuizResult(slug: string): QuizResult | null {
return isWorldSlug(slug) ? QUIZ_RESULTS[slug] : null;
}这里用到 DAY 26 学的字面量联合类型：WorldSlug 只能是三个值之一。Record<WorldSlug, QuizResult> 表示“每个 slug 都必须有一条结果”，少写一个 TypeScript 就报错。value is WorldSlug 叫类型守卫：函数返回 true 时，TypeScript 就知道这个字符串一定是三个 slug 之一。文案守住“说事情不说情话”：说具体的场景，不说肉麻的话。如果你的测试小游戏里已经有结果文案，就从那里导入，不要复制两份。
dongge-web/app/quiz/result/[slug]/page.tsx
import type { Metadata } from "next";
import Link from "next/link";
import { notFound } from "next/navigation";
import { QUIZ_RESULTS, getQuizResult } from "@/lib/quiz-results";
import { ogDefaults } from "@/lib/site";
type Props = { params: Promise<{ slug: string }> };
export function generateStaticParams() {
return Object.keys(QUIZ_RESULTS).map((slug) => ({ slug }));
}
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { slug } = await params;
const result = getQuizResult(slug);
if (!result) {
return { title: "没有这个结果" };
}
const title = `我的测试结果：${result.name}`;
const description = `${result.feeling}。${result.line}`;
return {
title,
description,
openGraph: { ...ogDefaults, title, description },
};
}
export default async function QuizResultPage({ params }: Props) {
const { slug } = await params;
const result = getQuizResult(slug);
if (!result) notFound();
return (
<main className="mx-auto max-w-xl px-4 py-16 text-center">
<p className="text-sm text-neutral-500">你最需要的东哥是</p>
<h1 className="mt-2 text-4xl font-bold">{result.name}</h1>
<p className="mt-2 text-lg">给你{result.feeling}</p>
<p className="mt-6 text-neutral-700">{result.line}</p>
<Link
href="/quiz"
className="mt-10 inline-block rounded-full bg-neutral-900 px-6 py-3 text-white"
>
我也测一测
</Link>
</main>
);
}逐段解释：generateStaticParams 告诉 Next.js 构建时把三个结果页都提前生成好，访问时直接返回静态页面，最快。generateMetadata 给每个结果写自己的标题和描述，这里写了 openGraph，所以用 ...ogDefaults 把网站名等共用信息补回来。页面里访问不存在的 slug（比如 /quiz/result/abc）会调用 notFound()。朋友打开这个页面，看到的是结果和一个“我也测一测”的按钮，这就是分享带来新访客的路径。
dongge-web/app/quiz/result/[slug]/opengraph-image.tsx
import { ImageResponse } from "next/og";
import { QUIZ_RESULTS, getQuizResult } from "@/lib/quiz-results";
import { loadGoogleFont } from "@/lib/og-font";
export const alt = "三岁的东哥 测试结果";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";
export default async function Image({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
const result = getQuizResult(slug) ?? QUIZ_RESULTS.gentleman;
const feelingText = `给我${result.feeling}`;
const allText = `三岁的东哥我最需要的是${result.name}${feelingText}${result.line}`;
const font = await loadGoogleFont("Noto+Sans+SC:wght@700", allText);
return new ImageResponse(
(
<div
style={{
width: "100%",
height: "100%",
display: "flex",
flexDirection: "column",
justifyContent: "center",
padding: "80px",
background: result.background,
color: "#ffffff",
fontFamily: "Noto Sans SC",
}}
>
<div style={{ fontSize: 32, color: result.accent }}>三岁的东哥</div>
<div style={{ fontSize: 44, marginTop: 40 }}>我最需要的是</div>
<div style={{ fontSize: 120, marginTop: 8 }}>{result.name}</div>
<div style={{ fontSize: 40, marginTop: 8, color: result.accent }}>{feelingText}</div>
<div style={{ fontSize: 30, marginTop: 40, opacity: 0.85 }}>{result.line}</div>
</div>
),
{
...size,
fonts: [{ name: "Noto Sans SC", data: font, style: "normal", weight: 700 }],
}
);
}这个文件和页面在同一个文件夹，所以只作用于结果页，并且覆盖全站默认图。它的函数会收到和页面一样的 params。注意 feelingText 用模板字符串提前拼好：如果在 JSX 里写成 给我{result.feeling}，会变成两个子节点，这个 div 就得加 display: "flex"，否则报错。allText 把图里所有文字拼在一起交给字体函数，文案改了这里也会跟着变。找不到结果时退回绅士的配色，保证图片总能生成。
最后在测试小游戏的结果区加一个入口，写在你的测试客户端组件里（比如 components/Quiz.tsx）显示结果的位置，resultSlug 换成你代码里表示结果世界的变量：
<Link
href={`/quiz/result/${resultSlug}`}
className="mt-6 inline-block rounded-full bg-neutral-900 px-6 py-3 text-white"
>
分享我的结果
</Link>搜索引擎也有机器人（叫爬虫），它顺着链接一页页找内容。sitemap.xml 是你主动递过去的“页面清单”，告诉它网站有哪些页面；robots.txt 是门口的“告示牌”，告诉守规矩的爬虫哪些地方别进。Next.js 里用两个 TypeScript 文件生成它们：
dongge-web/app/sitemap.ts
import type { MetadataRoute } from "next";
import { SITE_URL } from "@/lib/site";
import { QUIZ_RESULTS } from "@/lib/quiz-results";
export default function sitemap(): MetadataRoute.Sitemap {
const slugs = Object.keys(QUIZ_RESULTS);
const paths = [
"",
"/links",
"/quiz",
"/ask",
...slugs.map((slug) => `/world/${slug}`),
...slugs.map((slug) => `/quiz/result/${slug}`),
];
return paths.map((path) => ({
url: `${SITE_URL}${path}`,
lastModified: new Date(),
}));
}dongge-web/app/robots.ts
import type { MetadataRoute } from "next";
import { SITE_URL } from "@/lib/site";
export default function robots(): MetadataRoute.Robots {
return {
rules: {
userAgent: "*",
allow: "/",
disallow: ["/admin", "/api/"],
},
sitemap: `${SITE_URL}/sitemap.xml`,
};
}逐行解释：sitemap 返回一个数组，每项是一个页面的完整网址和最后修改时间，Next.js 会把它转成标准的 XML，访问 /sitemap.xml 就能看到。路径列表要和你项目里的真实路由一致（提问箱如果在 /questions 就改成它）。robots 里 userAgent: "*" 表示对所有爬虫生效，允许访问全站，但不要进 /admin 和 /api/，最后告诉爬虫 sitemap 在哪。另外，在后台布局 app/admin/layout.tsx 里加一行 export const metadata: Metadata = { robots: { index: false, follow: false } };，让后台页面带上“不要收录”的标记。
第一种方法：在浏览器里打开页面，按 Cmd + Option + U 查看源代码，按 Cmd + F 搜索 og:，看标签是否齐全；把 og:image 的地址复制到新标签页打开，就能看到生成的图片。第二种方法：在终端里假装成 Facebook 的机器人去访问，只把 og 标签筛出来：
curl -s -A "facebookexternalhit/1.1" http://localhost:3000/quiz/result/street | grep -o '<meta property="og:[^>]*>'-s 表示安静模式，不显示进度；-A 设置访问者的身份（User-Agent）；grep -o 只输出匹配到的那一段。第三种方法：PR 的预览部署在 Vercel 后台的部署详情页里有一个 Open Graph 标签页，可以直接预览这个页面的卡片效果。最后才是真的发到聊天软件里看。聊天软件会缓存卡片，第一次抓错了，之后可能一直显示旧的，测试时可以在网址后面加 ?v=2 这样的参数，让它当成新链接重新抓取。不同软件读取卡片的规则不完全一样，有的软件在聊天里不显示网页自带的分享图，以你实际测试的结果为准。
找到分享卡片的 issue，新建分支
cd ~/code/dongge-web
git switch main
git pull
gh issue list --label seo
git switch -c feat/share-cards补全验收标准
用 gh issue view 编号 --web 打开 issue，对照下面这张清单，把缺的验收标准补进 issue 正文（点编辑按钮修改）：
og:image，地址是完整网址。/quiz/result/gentleman、street、thai 三个页面存在，分享图显示对应的世界名、感受和配色，中文没有方块。/sitemap.xml 列出所有前台页面，/robots.txt 禁止 /admin 和 /api/，后台页面带 noindex。自己写 lib/site.ts
这个文件很短，照上午的代码亲手写，把 SITE_URL 换成你 Vercel 上的真实网址（在 Vercel 项目首页的 Domains 里能看到）。
Plan 模式出实现方案
切到 Plan 模式，发送“问 Claude”第 1 条提示词。审查它列出的文件清单：有没有新增依赖（今天一个都不需要）？结果页网址是不是 /quiz/result/世界名？普通页面是不是只写 title 和 description？
实现页面元信息，逐页审查
切回 Manual 模式，让 Claude 按方案实现根布局和各页面的 metadata、lib/worlds.ts、后台 noindex。打开 diff 检查：根布局有 metadataBase 和 title.template；没有页面在 "use client" 文件里导出 metadata；描述文字具体、不油腻。然后运行“问 Claude”第 2 条提示词，让它用表格列出每页最终的标题和描述，你逐行过一遍。
全站分享图
加上 lib/og-font.ts 和 app/opengraph-image.tsx，运行 npm run dev，在浏览器打开：
http://localhost:3000/opengraph-image测试结果页和专属分享图
加上 lib/quiz-results.ts、结果页和结果页的 opengraph-image.tsx，再在测试组件的结果区加“分享我的结果”链接。依次打开三个结果页，再用查看源代码找到每页的 og:image 地址打开。
/quiz/result/abc 显示 404。sitemap 和 robots
加上 app/sitemap.ts 和 app/robots.ts，在浏览器打开 http://localhost:3000/sitemap.xml 和 http://localhost:3000/robots.txt。
SITE_URL 开头；robots.txt 里有两行 Disallow 和一行 Sitemap。像机器人一样检查
curl -s -A "facebookexternalhit/1.1" http://localhost:3000/ | grep -o '<meta property="og:[^>]*>'
curl -s -A "facebookexternalhit/1.1" http://localhost:3000/links | grep -o '<title>[^<]*</title>'
curl -s -A "facebookexternalhit/1.1" http://localhost:3000/quiz/result/thai | grep -o '<meta property="og:[^>]*>'构建、测试、开 PR
npm run lint
npx tsc --noEmit
npm test
npm run build构建输出的路由列表里，能看到 /quiz/result/[slug] 下面生成了三个路径，还有 /opengraph-image、/sitemap.xml、/robots.txt。然后提交、推送，用 gh pr create 开 PR，描述里写 Closes #编号。
在预览部署里看卡片
等 PR 的预览部署完成，在 Vercel 后台打开这次部署的详情页，找到 Open Graph 标签页，分别查看首页和一个结果页的卡片预览。有问题就把现象写清楚让 Claude 改，再推一次。
合并，发到聊天软件里验收
CI 通过后合并。等线上部署完成，把 你的网址/quiz/result/street 发给自己或一位朋友（用 Messenger、WhatsApp、Telegram 或 iMessage 这类会显示卡片的软件），在手机上看卡片。如果显示的还是旧样子，在网址后面加 ?v=2 再发一次。明天给提问箱和文案助手加限流，并做好 404 和 500 页面。
loadGoogleFont 的第二个参数漏了图里的某些字。改了文案要确认它也被拼进了 allText；同时看终端有没有“分享图字体加载失败”的报错，多半是网络问题。display: "flex"，或者像 feelingText 那样先用模板字符串把文字拼成一段。?v=2 重新发送；Facebook 系的平台可以用 Sharing Debugger 让它重新抓取。"use client" 组件，页面本身不写 "use client"。openGraph 就会整个替换根布局的。用 ...ogDefaults 把共用字段展开进去。把网址发到聊天软件里，预览卡片好看吗？
按四点检查：标题是否是这个页面自己的（比如“我的测试结果：街头”），不是全站统一的一句；描述是否一眼能看懂、不油腻；图片在手机聊天框这么小的尺寸下字还看不看得清，有没有方块或被裁掉；三种结果的图能不能一眼分出来。任何一点不满意，都能具体说出改哪个文件：标题描述在 generateMetadata，图片在 opengraph-image.tsx。
为什么测试结果必须有自己的网址，才能有专属分享图？
聊天软件的机器人只拿到一个网址，它访问这个网址、读服务器返回的 HTML 里的 og 标签。原来的结果只存在于粉丝浏览器里的 React state 中，机器人访问 /quiz 只能看到测试的开头，不知道她测出了什么。给每种结果一个独立网址（/quiz/result/street），服务器就能针对这个网址返回专属的标题、描述和分享图。
robots.txt 里写了 Disallow: /admin，后台就安全了吗？
不安全。robots.txt 只是给守规矩的搜索引擎爬虫看的建议，浏览器和恶意脚本完全可以无视它；它还等于公开告诉别人“后台在 /admin”。后台的安全靠的是服务端的登录检查：页面、Server Action、Route Handler 开头都验证登录状态。Disallow 和 noindex 的作用只是让后台页面不出现在搜索结果里。
not-found.tsx、error.tsx、global-error.tsx，并说出它们分别在什么时候出现、为什么不显示真实的报错信息。昨天做好了分享卡片，网址很快会被更多人看到。看到的人里，绝大多数是正常的粉丝，但也会有人写个脚本对着提问箱一秒提交几百次，或者有爬虫程序不停地试探你的接口。DAY 44 你做过“防止连点重复提交”，那是在浏览器里把按钮变灰；DAY 45 你学过，脚本根本不经过你的页面，它直接向服务器发请求，按钮灰不灰和它没关系。
被刷会带来三种损失：数据库被垃圾数据塞满（Neon 免费版有存储上限），后台审核队列被淹没（你的时间），以及文案助手每调用一次 Claude API 都要花钱（你的账单）。今天从四个方面加固：限流（控制频率）、长度限制（控制每次的大小）、防机器人（识别脚本）、错误页（出了错也体面，而且不泄露内部信息）。
网红奶茶店门口常挂一块牌子：“每人每 10 分钟限购 3 杯”。这句话包含了限流的全部要素：
怎么算“10 分钟内”？常见两种算法。固定窗口：把时间切成 10:00 到 10:10、10:10 到 10:20 这样的格子，每格重新计数，简单，但有个漏洞：10:09 买 3 杯、10:10 又买 3 杯，一分钟内买了 6 杯。滑动窗口：每次都往回看“最近 10 分钟”，没有这个漏洞。今天用滑动窗口：每次请求记一条带时间的记录，判断时数一数最近 10 分钟内有几条。
IP 地址从哪来？请求经过 Vercel 时，Vercel 会在请求头 x-forwarded-for 里写上访客的公网 IP。Vercel 文档说明它会覆盖这个请求头、不转发外部传入的值，目的就是防止有人伪造 IP。要注意这是 Vercel 平台的保证，换到别的服务器上，这个请求头可能被访客随便改。另外，IP 属于个人信息，我们不存原始 IP，而是存它的哈希值（一种单向的“指纹”，能判断两次是不是同一个 IP，但反推不出原来的地址）。
| 方案 | 怎么做 | 优点 | 缺点 |
|---|---|---|---|
| 数据库记录 | 在 Neon 里加一张表，每次请求查一次、写一次 | 不加新服务、新库、新密钥；代码全在你手里，看得懂、好调试 | 每次多一两次数据库查询（几十毫秒）；同一瞬间的并发请求可能多放行一两个；要定期清理旧记录 |
| Upstash Redis | 注册 Upstash，安装 @upstash/ratelimit 等库，加新的环境变量 | 专为计数设计，速度快，计数是原子的（不会多放行） | 多一个服务、账号和密钥；超出本课固定的技术栈 |
| Vercel WAF 规则 | 在 Vercel 后台 Firewall 里新建规则，不写代码 | 在请求到达你的代码之前就拦住 | 官方文档写明 Hobby 版每个项目只有 1 条限流规则，窗口 10 秒到 10 分钟；只能按请求特征配置，写不了“登录用户每分钟 10 次”这种业务规则 |
你的网站流量不大，每分钟几次到几十次提问，数据库方案完全够用，而且不引入新东西，符合 CLAUDE.md 里“不换库、不加依赖”的规矩。它的并发漏洞（同一毫秒两个请求可能都通过）对“防止被刷几百条”来说影响很小。等哪天流量大到数据库扛不住，再换 Upstash 或加 WAF 规则，这就是先做够用的、再按需升级。
先在 schema 里加一张记录表。每条记录只有“谁”和“什么时候”：
dongge-web/prisma/schema.prisma（末尾新增）
model RateLimitHit {
id String @id @default(cuid())
key String
createdAt DateTime @default(now())
@@index([key, createdAt])
}key 存“谁在做什么”，比如 ask:ip:哈希值；@@index([key, createdAt]) 是 DAY 41 学过的索引，因为每次都要按 key 和时间查，有索引才快。
然后把“不碰数据库、不碰请求”的纯计算逻辑单独放一个文件，这样可以用 Vitest 直接测试：
dongge-web/lib/rate-limit-utils.ts
import { createHash } from "node:crypto";
export function parseClientIp(forwardedFor: string | null): string {
if (!forwardedFor) return "unknown";
const first = forwardedFor.split(",")[0].trim();
return first ? first : "unknown";
}
export function hashIdentifier(value: string): string {
const salt = process.env.BETTER_AUTH_SECRET ?? "";
return createHash("sha256").update(`${salt}:${value}`).digest("hex").slice(0, 32);
}
export function retryAfterSeconds(oldestMs: number, windowMs: number, nowMs: number): number {
return Math.max(1, Math.ceil((oldestMs + windowMs - nowMs) / 1000));
}逐个解释：x-forwarded-for 可能是“访客IP, 中间代理IP”这样用逗号隔开的一串，第一个才是访客，取不到就记成 unknown。hashIdentifier 用 Node 自带的 crypto 算 SHA-256 哈希，前面拼上一段秘密的“盐”，这里借用已有的 BETTER_AUTH_SECRET，省得再加一个环境变量；加盐是因为 IPv4 地址总共只有四十多亿个，不加盐的话别人可以把所有 IP 都算一遍反查出来。retryAfterSeconds 算“还要等几秒”：最早那条记录过期的时刻减去现在，向上取整，至少 1 秒。
dongge-web/lib/rate-limit.ts
import { headers } from "next/headers";
import { prisma } from "@/lib/prisma";
import { parseClientIp, retryAfterSeconds } from "@/lib/rate-limit-utils";
export { hashIdentifier } from "@/lib/rate-limit-utils";
export async function getClientIp(): Promise<string> {
const headerList = await headers();
return parseClientIp(headerList.get("x-forwarded-for"));
}
type RateLimitOptions = {
key: string;
limit: number;
windowMs: number;
};
type RateLimitResult = { ok: true } | { ok: false; retryAfterSec: number };
export async function checkRateLimit({
key,
limit,
windowMs,
}: RateLimitOptions): Promise<RateLimitResult> {
const now = Date.now();
const windowStart = new Date(now - windowMs);
const recent = await prisma.rateLimitHit.findMany({
where: { key, createdAt: { gte: windowStart } },
orderBy: { createdAt: "asc" },
select: { createdAt: true },
take: limit,
});
if (recent.length >= limit) {
const oldestMs = recent[0].createdAt.getTime();
return { ok: false, retryAfterSec: retryAfterSeconds(oldestMs, windowMs, now) };
}
await prisma.rateLimitHit.create({ data: { key } });
if (Math.random() < 0.01) {
await prisma.rateLimitHit.deleteMany({
where: { createdAt: { lt: new Date(now - 24 * 60 * 60 * 1000) } },
});
}
return { ok: true };
}逐段解释：getClientIp 用 headers() 读取请求头，新版 Next.js 里它是异步函数，要 await，Server Action 和 Route Handler 里都能用。RateLimitResult 是一个联合类型：要么是 { ok: true }，要么是带着等待秒数的 { ok: false }，调用方判断 ok 之后，TypeScript 就知道能不能读 retryAfterSec。
checkRateLimit 的核心三步：先查出这个 key 在窗口内最早的几条记录，最多查 limit 条就够了；如果已经有 limit 条，说明到上限了，直接返回“不通过”，而且不写入新记录，否则被拒绝的请求也会不断把窗口往后推；没到上限就写入一条，返回“通过”。最后那段是“顺手打扫”：每次有 1% 的概率删掉一天前的旧记录，不用专门设定时任务，表也不会无限变大。
在提问箱的 Server Action 里，检查的顺序有讲究：先做不花钱的检查，再做要查数据库的检查。下面是完整的 action，函数名、Zod 规则名按你 DAY 43 到 44 写的来（如果你用 useActionState，参数就是这种“上一次的状态加表单数据”的形式）：
dongge-web/app/ask/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { prisma } from "@/lib/prisma";
import { questionSchema } from "@/lib/validations";
import { checkRateLimit, getClientIp, hashIdentifier } from "@/lib/rate-limit";
export type AskState = { ok: boolean; message: string };
const THANKS = "收到了，审核后会显示在提问箱里。";
export async function submitQuestion(_prev: AskState, formData: FormData): Promise<AskState> {
// 1. 蜜罐：真人看不到这个输入框，脚本往往会把所有输入框都填上
if (formData.get("website")) {
return { ok: true, message: THANKS };
}
// 2. 校验内容和长度（不查数据库，最便宜）
const parsed = questionSchema.safeParse({
content: formData.get("content"),
nickname: formData.get("nickname") || undefined,
});
if (!parsed.success) {
return { ok: false, message: parsed.error.issues[0]?.message ?? "内容格式不对" };
}
// 3. 限流：同一 IP 10 分钟最多 3 条；全站每小时最多 60 条
const ip = await getClientIp();
const perIp = await checkRateLimit({
key: `ask:ip:${hashIdentifier(ip)}`,
limit: 3,
windowMs: 10 * 60 * 1000,
});
if (!perIp.ok) {
const minutes = Math.ceil(perIp.retryAfterSec / 60);
return { ok: false, message: `提交太频繁了，请 ${minutes} 分钟后再试。` };
}
const siteWide = await checkRateLimit({ key: "ask:all", limit: 60, windowMs: 60 * 60 * 1000 });
if (!siteWide.ok) {
return { ok: false, message: "现在提问的人有点多，请过一会儿再来。" };
}
// 4. 保存，默认待审核
await prisma.question.create({
data: {
content: parsed.data.content,
nickname: parsed.data.nickname ?? null,
status: "PENDING",
},
});
revalidatePath("/admin/questions");
return { ok: true, message: THANKS };
}逐段解释：第 1 步是蜜罐（honeypot），下面马上讲，命中时假装成功，不告诉脚本它被识破了。第 2 步是 DAY 44 的 Zod 校验，不合格的请求在这里就被挡掉，一次数据库都不用查。第 3 步是两层限流：按 IP 防一个人刷，按全站总量防很多 IP 一起刷（比如对方换着 IP 来）。上限数字是示范，按你的实际情况定，但要和需求文档里写的一致。第 4 步保存时状态是 PENDING，即使有垃圾内容混进来，也要你审核通过才会出现在前台。
蜜罐的原理：在表单里放一个真人看不见的输入框。真人不会填它，而很多脚本会把所有输入框都填满。服务端发现它有值，就知道是脚本。在提问表单组件里加上：
dongge-web/components/AskForm.tsx（表单内新增）
<div aria-hidden="true" className="absolute -left-[9999px] h-px w-px overflow-hidden">
<label htmlFor="website">网站（请留空）</label>
<input id="website" name="website" type="text" tabIndex={-1} autoComplete="off" />
</div>这个输入框被移到屏幕左边很远的地方；aria-hidden 让读屏软件忽略它；tabIndex={-1} 让键盘 Tab 跳不到它；autoComplete="off" 防止浏览器自动填充把真人误伤。蜜罐挡不住专门针对你写的脚本，但能挡住大量“见表单就填”的通用机器人，成本几乎为零。
长度限制要做三层。第一层是输入框的 maxLength={300}，让粉丝打字时就知道上限，这是体验；第二层是 Zod 的 .max(300, "最多 300 字")，这是真正的防线，因为脚本可以绕过第一层；第三层可选，是数据库字段类型，比如 content String @db.VarChar(300)，作为最后的兜底。改字段类型要生成迁移，如果已有数据超长会失败，所以先查清楚再决定要不要加。
文案助手在后台，只有你能用，所以按登录用户的 id 限流，而不是按 IP：你换了网络 IP 会变，但你还是你。它每调用一次都花钱，限流是在 DAY 59“每天使用次数”基础上再加一层“每分钟不超过 10 次”，防止前端出 bug 时循环调用。如果文案助手是 Route Handler，在 POST 函数开头加上这几段，下面保留你原来调用 Claude API 的代码：
dongge-web/app/api/assistant/route.ts（开头部分）
import { headers } from "next/headers";
import { auth } from "@/lib/auth";
import { checkRateLimit } from "@/lib/rate-limit";
export async function POST(request: Request) {
const session = await auth.api.getSession({ headers: await headers() });
if (!session) {
return new Response("请先登录", { status: 401 });
}
const rl = await checkRateLimit({
key: `assistant:user:${session.user.id}`,
limit: 10,
windowMs: 60 * 1000,
});
if (!rl.ok) {
return new Response(`太快了，请 ${rl.retryAfterSec} 秒后再试`, {
status: 429,
headers: { "Retry-After": String(rl.retryAfterSec) },
});
}
// 下面保留你原来的输入校验和调用 Claude API 的代码
}先检查登录再限流：没登录的请求直接 401，根本不进入计数。超限时返回 429，并带上标准的 Retry-After 响应头告诉前端等几秒。如果你的文案助手是 Server Action，就在 action 开头做同样的检查，返回错误信息对象而不是 Response。
再严密的代码也会出错：数据库偶尔连不上、某条数据缺字段、粉丝输错网址。出错时如果显示一整屏英文报错，粉丝会以为网站坏了；如果报错里带着文件路径、SQL 语句，还会把内部信息暴露给坏人。Next.js 用三个特殊文件处理错误：
| 文件 | 什么时候出现 | 要点 |
|---|---|---|
app/not-found.tsx | 网址不存在，或代码里调用了 notFound() | 默认是服务端组件；返回 404 状态码 |
app/error.tsx | 页面渲染时抛出了没被处理的错误 | 必须是客户端组件；包在布局里面，导航栏还在 |
app/global-error.tsx | 连根布局本身都出错了 | 替换整个根布局，要自己写 <html> 和 <body>，自己引入样式 |
dongge-web/app/not-found.tsx
import Link from "next/link";
export default function NotFound() {
return (
<main className="mx-auto flex min-h-[60vh] max-w-md flex-col items-center justify-center px-4 text-center">
<p className="text-sm text-neutral-500">404</p>
<h1 className="mt-2 text-2xl font-bold">这一页走丢了</h1>
<p className="mt-3 text-neutral-600">可能是网址写错了，或者这个页面已经下线。</p>
<div className="mt-8 flex gap-3">
<Link href="/" className="rounded-full bg-neutral-900 px-5 py-3 text-white">
回首页
</Link>
<Link href="/quiz" className="rounded-full border border-neutral-300 px-5 py-3">
做个小测试
</Link>
</div>
</main>
);
}dongge-web/app/error.tsx
"use client";
import { useEffect } from "react";
import Link from "next/link";
export default function ErrorPage({
error,
retry,
}: {
error: Error & { digest?: string };
retry: () => void;
}) {
useEffect(() => {
console.error(error);
}, [error]);
return (
<main className="mx-auto flex min-h-[60vh] max-w-md flex-col items-center justify-center px-4 text-center">
<p className="text-sm text-neutral-500">500</p>
<h1 className="mt-2 text-2xl font-bold">页面出了点问题</h1>
<p className="mt-3 text-neutral-600">不是你的错。可以再试一次，还是不行就过一会儿再来。</p>
{error.digest && (
<p className="mt-2 text-xs text-neutral-400">错误编号：{error.digest}</p>
)}
<div className="mt-8 flex gap-3">
<button
type="button"
onClick={() => retry()}
className="rounded-full bg-neutral-900 px-5 py-3 text-white"
>
再试一次
</button>
<Link href="/" className="rounded-full border border-neutral-300 px-5 py-3">
回首页
</Link>
</div>
</main>
);
}逐段解释：error.tsx 是 React 的“错误边界”，只能在浏览器里工作，所以第一行必须是 "use client"。它收到两个参数：error 是错误对象，retry 是“重新获取数据并重新渲染”的函数。官方文档说明，生产环境里从服务端组件传过来的错误，error.message 会被换成一句通用的话，避免泄露敏感信息；取而代之的是 error.digest，一串自动生成的错误编号，它和服务器日志里的记录对应。所以页面上只显示编号，不显示 message。粉丝把编号截图发给你，明天你就能用它在 Vercel 日志里找到真正的原因。
retry 是 Next.js 16.3 起稳定的参数名，更早的版本只有 reset。运行 npx next --version 看版本，低于 16.3 就把代码里的 retry 全部换成 reset，以官方文档为准。dongge-web/app/global-error.tsx
"use client";
import "./globals.css";
export default function GlobalError({
error,
retry,
}: {
error: Error & { digest?: string };
retry: () => void;
}) {
return (
<html lang="zh-CN">
<body className="flex min-h-screen items-center justify-center bg-white px-4 text-center">
<title>出错了 | 三岁的东哥</title>
<main>
<h1 className="text-2xl font-bold">网站暂时出了问题</h1>
<p className="mt-3 text-neutral-600">请稍后刷新页面再试。</p>
{error.digest && (
<p className="mt-2 text-xs text-neutral-400">错误编号：{error.digest}</p>
)}
<button
type="button"
onClick={() => retry()}
className="mt-6 rounded-full bg-neutral-900 px-5 py-3 text-white"
>
再试一次
</button>
</main>
</body>
</html>
);
}global-error.tsx 出现时，根布局已经不在了，所以它要自己写 <html> 和 <body>，自己 import "./globals.css"，否则 Tailwind 样式不生效。它是客户端组件，不能导出 metadata，官方文档建议直接用 React 的 <title> 标签设置标题。它很少出现，写得简单可靠就行。明天你会故意制造一个错误，在 Vercel 日志里用错误编号把它找出来。
找到安全 issue，新建分支
cd ~/code/dongge-web
git switch main
git pull
gh issue list --label security
git switch -c feat/rate-limit写清验收标准
打开 issue，确认或补充这些验收标准（数字按你的需求文档）：
加表并生成迁移
先确认 .env 里的 DATABASE_URL 指向开发用的数据库，而不是正式库（DAY 54 你把两者分开了）。把 RateLimitHit 模型加进 prisma/schema.prisma，然后：
npx prisma migrate dev --name add_rate_limit_hit
npx prisma generateprisma/migrations 里多了一个以 add_rate_limit_hit 结尾的文件夹，里面的 SQL 有 CREATE TABLE "RateLimitHit"。下任务：工具函数和单元测试
把“问 Claude”第 1 条提示词发给 Claude。它会先给方案，你对照上午的代码确认表结构和函数签名，再让它写 lib/rate-limit-utils.ts、lib/rate-limit.ts 和测试文件。测试文件应该类似这样：
dongge-web/lib/rate-limit-utils.test.ts
import { describe, expect, it } from "vitest";
import { parseClientIp, retryAfterSeconds } from "./rate-limit-utils";
describe("parseClientIp", () => {
it("取 x-forwarded-for 里的第一个地址", () => {
expect(parseClientIp("203.0.113.7, 10.0.0.1")).toBe("203.0.113.7");
});
it("没有请求头时返回 unknown", () => {
expect(parseClientIp(null)).toBe("unknown");
});
it("只有空格时返回 unknown", () => {
expect(parseClientIp(" ")).toBe("unknown");
});
});
describe("retryAfterSeconds", () => {
it("不足 1 秒也按 1 秒算", () => {
expect(retryAfterSeconds(0, 60_000, 59_500)).toBe(1);
});
it("窗口刚开始时要等满整个窗口", () => {
expect(retryAfterSeconds(0, 600_000, 0)).toBe(600);
});
});npm test审查限流核心代码
打开 diff，按这张清单逐项看 lib/rate-limit.ts：key 里的 IP 是经过 hashIdentifier 处理的；被拒绝时没有写入新记录；有清理旧记录的逻辑；没有新增任何 npm 依赖（看 package.json 没变）。有看不懂的行，直接问 Claude “第几行为什么这样写”。
接进提问箱，加蜜罐和长度限制
让 Claude 按上午的顺序（蜜罐、校验、限流、保存）改提问箱的 Server Action，在表单组件里加蜜罐字段，给输入框加 maxLength，并确认 Zod 规则里有 .max(300)。审查时重点看顺序对不对。
接进文案助手
让 Claude 在文案助手的入口（Route Handler 或 Server Action）开头加上登录检查和按用户 id 的限流。确认登录检查在限流之前。
本地手动测试限流和蜜罐
运行 npm run dev，在提问箱连续提交 4 条内容为“【测试】限流”的提问。然后在 Neon 控制台的 SQL 编辑器（选开发用的分支）里运行：
SELECT key, "createdAt" FROM "RateLimitHit" ORDER BY "createdAt" DESC LIMIT 10;再测蜜罐：打开开发者工具的 Console，输入下面这行后回车，再正常提交一次：
document.querySelector("#website").value = "http://spam.example";ask:ip: 加一串字母数字，看不到 IP；蜜罐那次页面显示成功，但 Question 表里没有新记录。本地所有请求可能都记成同一个 unknown，这是正常的。做好三个错误页
新建 app/not-found.tsx、app/error.tsx、app/global-error.tsx（可以让 Claude 按上午的代码写，你来审文案）。先检查版本决定用 retry 还是 reset：
npx next --version访问 http://localhost:3000/abc 和 http://localhost:3000/world/abc，应该都显示“这一页走丢了”。
临时制造一个错误，看 error.tsx
在 app/links/page.tsx 的页面函数第一行临时加上：
throw new Error("测试 error.tsx");刷新链接页。开发模式会先弹出红色的报错遮罩，按 Esc 关掉，就能看到你的错误页。看完立刻删掉这一行，用 git diff app/links/page.tsx 确认没有残留。
检查、提交、合并，处理正式库迁移
npm run lint
npx tsc --noEmit
npm test
npm run build
git add -A
git status
git commit -m "feat: 提问箱和文案助手限流、蜜罐、错误页"
git push -u origin feat/rate-limit
gh pr create --title "feat: 安全加固（限流与错误页）" --body "Closes #编号"合并前想清楚：正式库也需要 RateLimitHit 表。按 DAY 54 定下的方式把迁移应用到正式库（比如构建时运行 prisma migrate deploy），否则上线后提问箱会报错。
线上验收，回答今天的问题
部署完成后，在线上提问箱连续提交 4 条“【测试】限流”，确认第 4 条被拒绝，然后到后台把这几条测试提问隐藏。最后写下你对“有人用脚本每秒提交 100 条提问，现在会怎样”的回答，和参考答案对照。明天学备份恢复和看日志，用今天的错误编号去日志里找原因。
migrate dev 不会自动生成客户端，运行 npx prisma generate，再重启开发服务器。x-forwarded-for，所有请求都记成 unknown。这是预期行为，部署到 Vercel 后才会按真实 IP 计数。npm run build 加 npm run start 测试。reset，把代码里的 retry 换掉。有人用脚本每秒提交 100 条提问，现在会怎样？
脚本绕过页面直接调用 Server Action。如果它把蜜罐字段也填了，所有请求都被假装成功地丢弃。如果内容超长或为空，Zod 在查数据库之前就拒绝。剩下的合格请求，同一个 IP 在 10 分钟里只有前 3 条被保存，其余的返回“提交太频繁”且不写入；如果对方换很多 IP，全站每小时 60 条的总上限会兜底。被保存的最多几十条都是 PENDING 状态，要你审核后才出现在前台。剩下的风险：每个被拒绝的请求仍然要查一次数据库，量非常大时数据库压力会上升；全站上限被打满时，正常粉丝这一小时也提交不了。那时可以在 Vercel WAF 里加一条规则，在请求到达代码之前拦截。
为什么错误页上不直接显示 error.message？error.digest 有什么用？
服务端的报错信息里可能有文件路径、SQL 语句、第三方服务的返回内容，显示给访客等于把内部信息交给坏人，所以 Next.js 在生产环境里会把服务端错误的 message 换成通用的话。digest 是这次错误自动生成的编号，同一个编号也会出现在服务器日志里。访客只看到编号，你拿着编号去 Vercel 日志里就能找到完整的报错和堆栈，两边既安全又能对上号。
文案助手为什么按用户 id 限流，而提问箱按 IP？
文案助手在后台，只有登录的管理员能用，每个请求都知道“是谁”，按用户 id 计数最准确：你换网络 IP 会变，但 id 不变。提问箱是公开的，粉丝不用登录，服务器只能靠 IP 大致区分不同的人。IP 不完美（同一个 Wi-Fi 下的人共用一个 IP，换网络能换 IP），所以提问箱还加了全站总量上限作为兜底。
pg_dump 做一份自己保管的备份，并验证这份文件能被读取。昨天你给网站加了限流和错误页，防的是“外面的人”。今天防的是另外两类事：自己手滑，和系统出错。想象三个场景：你在 Neon 的 SQL 编辑器里想删一条测试 look，忘了写 WHERE，整张表清空了；你合并了一个迁移，把 Question 表的一列改错了，粉丝的提问全乱了；网站突然打不开，你不知道是哪里坏了。前两个靠备份，第三个靠日志。
讨论备份时有两个问题最重要，用大白话说：第一，出事后能回到多久以前，也就是“最多丢多少数据”；第二，恢复要花多长时间，也就是“网站要停多久”。你的网站是个人 IP 官网，丢几小时的提问还能接受，丢掉所有 looks 和后台记录就很痛。所以今天的目标是：知道 Neon 自带的恢复能力有多大，再自己多留一份。
还有一句运维圈的老话：没演练过的备份，等于没有备份。很多人以为自己有备份，真出事时才发现文件是空的、密码忘了、步骤不会。所以今天不只是“了解”，而是亲手演练一遍，并把步骤写进故障手册。
Neon 不是每天夜里拍一张快照那种传统备份。它会持续记录数据库的每一次变化，所以你可以回到过去某个具体的时间点。能回到多久以前，叫“历史窗口”（history window）。按 Neon 官方文档，免费版是 6 小时，而且不能延长；付费的 Launch 和 Scale 套餐默认 1 天，最多可以分别调到 7 天和 30 天。套餐和数字会调整，以官方文档和你控制台里显示的为准。
6 小时是什么意思？如果你早上 9 点误删了数据，下午 3 点之前发现，还能用 Neon 找回来；晚上才发现，就超出窗口了。这就是后面还要用 pg_dump 自己留一份的原因。
Neon 的另一个核心概念是分支（branch），和 Git 的分支很像。创建分支时不会真的复制一份数据，而是“写时复制”：新分支和父分支共享原来的数据，谁改了什么，就只额外存改动的部分。所以建一个分支几乎是瞬间完成的，也不影响正式库的性能。最有用的一点是：建分支时可以选择“过去的数据”，也就是从过去某个时间点的样子分出一个新分支。在控制台里的操作是：侧边栏 Branches，点 New branch，选父分支，内容选 Past data 并挑一个时间，再点 Create。每个分支有自己的连接方式，在 SQL 编辑器里可以切换到这个分支查询。官方文档写明免费版的根分支数量有限，演练完记得删掉用不到的分支。
| 情况 | 用什么 | 怎么做 | 代价 |
|---|---|---|---|
| 误删或改错了几条数据，还在历史窗口内 | 从过去时间点建分支 | 在分支里查出旧数据，再用 INSERT 或 UPDATE 放回正式分支 | 要手动拷数据，但正式库里其他新数据都保留 |
| 整个库被改坏了（比如迁移写错），还在窗口内 | 整个分支回退（Restore from history） | 在控制台 Backup & Restore 页面选时间点，确认后恢复 | 那个时间点之后的所有新数据（比如新的提问）都会一起回退 |
| 超出历史窗口，或者 Neon 本身出了问题 | 自己的 pg_dump 备份文件 | 用 pg_restore 把文件恢复到一个新的空数据库 | 只能回到最近一次备份的时间 |
第二种要多说几句。官方文档说明，整个分支回退时，Neon 会自动把回退前的状态保存成一个备份分支，名字形如“分支名_old_时间”，万一回退错了还能再换回来；回退后数据库的连接地址不变，网站不用改配置。但它的代价很大：那个时间点之后粉丝提交的提问、你新发的 look，都会消失。所以日常误删几条，优先用第一种；只有整库被搞坏时才用第二种，而且动手前先想清楚会丢掉什么。今天的演练用第一种，第二种只需要知道在哪、有什么后果。
pg_dump 是 PostgreSQL 官方的导出工具，能把整个数据库（表结构加数据）导出成一个文件，存在你自己的电脑上。它不依赖 Neon 的历史窗口，超过 6 小时也能用。Mac 上用 Homebrew 安装 PostgreSQL 的客户端工具包 libpq，里面就有 pg_dump 和 pg_restore：
brew install libpq
echo 'export PATH="$(brew --prefix libpq)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
pg_dump --version逐行解释：第一行安装 libpq；它默认不放进系统路径（Homebrew 称为 keg-only，避免和其他版本冲突），所以第二行往 ~/.zshrc 末尾追加一行，把它的 bin 目录加到 PATH 里；第三行让配置立刻生效；第四行确认能用，并看版本号。Neon 官方文档建议使用最新版的 pg_dump，并让客户端版本和 Neon 项目的 Postgres 版本一致或更新。
导出时有两个要点，都来自 Neon 的文档：第一，不要用带连接池的连接串（地址里有 -pooler 的那种），要用直连的连接串，在 Neon 控制台点 Connect，把连接池（Connection pooling）选项关掉就能拿到；第二，推荐用 -Fc 格式导出，之后用 pg_restore 恢复。连接串里有数据库密码，所以不要把它直接写在命令里（会留在终端历史记录中），而是用 zsh 的 read -s 临时输入：
mkdir -p ~/backups/dongge-web
read -s "NEON_DIRECT_URL?粘贴不带 -pooler 的连接串，然后回车："
echo
pg_dump -Fc -v -d "$NEON_DIRECT_URL" -f ~/backups/dongge-web/dongge-web-$(date +%Y%m%d).dump
unset NEON_DIRECT_URL逐行解释：备份放在 ~/backups，在项目文件夹之外，永远不会被 Git 提交。read -s 读取你粘贴的内容但不显示在屏幕上，存进变量 NEON_DIRECT_URL；问号后面是提示文字。echo 只是换一行。pg_dump 的 -Fc 是自定义压缩格式，-v 显示过程，-d 是连接串，-f 是输出文件，$(date +%Y%m%d) 会被替换成今天的日期，比如 20261010。最后 unset 把变量清掉。
怎么确认备份文件是好的？最简单的方法是列出它的目录：pg_restore --list 文件名，能看到 World、Look、Question 等表的条目，说明文件完整可读。真正恢复时，Neon 文档的做法是先准备一个同名的空数据库（比如新建一个分支），再运行 pg_restore -v -d "目标连接串" 文件名。这份文件里有你所有的数据，包括 Better Auth 的用户表，像对待密码一样对待它：不上传到公开的地方，不发给别人。
Vercel 上有两种日志，别搞混。构建日志（Build Logs）记录的是 npm run build 的过程，部署失败时看它，在部署详情页里。运行时日志（Runtime Logs）记录的是网站运行中每一次请求的情况，包括你的服务端代码里 console.log 和 console.error 打印的内容，线上出错时看它，在项目侧边栏的 Logs 里。
Logs 页面左边是筛选器，最常用的几个：时间范围（Timeline，还有实时跟随的 Live 模式）、级别（Level）、路由（Route，比如 /world/[slug]）、请求路径（Request Path，比如 /world/street）、状态码（Status Code）、环境（Environment，production 或 preview）、分支（Branch）。顶部搜索框可以按日志内容搜索。点开任意一行，右侧会显示这次请求的详细信息和它打印的所有日志。按官方文档，console.log 记为 info，console.error 记为 error；状态码 4xx 的请求标黄色警告，5xx 标红色错误；界面上的时间都是 UTC（比新加坡时间晚 8 小时）。
如果你装了 Vercel 的命令行工具，也可以在终端里查日志，比如 vercel logs --level error --since 1h 查最近一小时的错误。这是可选的，今天用网页就够了。
昨天你在错误页上显示了 error.digest。它的价值在今天体现：页面在服务器上渲染出错时，Next.js 会在服务器日志里打印完整的报错信息和堆栈，通常还带着同一个 digest 编号。访客看到的只有编号，你拿编号去 Logs 里搜，就能找到真正的原因，两边对上号。
对于你自己能预料到可能失败的地方（比如保存到数据库），好的做法是用 try/catch 接住错误，打一条有用的日志，再给用户一个友好的提示。日志要写得“半年后的你也能看懂”，同时绝不记录个人信息和密钥：
dongge-web/app/ask/actions.ts（第 4 步“保存”改成这样）
try {
await prisma.question.create({
data: {
content: parsed.data.content,
nickname: parsed.data.nickname ?? null,
status: "PENDING",
},
});
} catch (error) {
console.error("[ask] 保存提问失败", {
message: error instanceof Error ? error.message : String(error),
});
return { ok: false, message: "保存失败了，请稍后再试。" };
}逐行解释：try 里放可能失败的数据库操作；失败时进入 catch。console.error 的第一个参数以 [ask] 开头，方便在 Logs 里搜索“是哪个功能出的错”，后面一句中文说明发生了什么；第二个参数只放错误信息本身。error instanceof Error 判断它是不是标准的错误对象，是就取 message，不是就转成字符串。注意这里没有记录提问内容、昵称和 IP：日志会被保存、会被你分享给别人帮忙看，个人信息不该出现在里面。最后给用户返回一句友好的话，而不是让页面崩掉。
更进一步是“错误监控”：出错时自动发邮件或消息提醒你，并把同类错误归并统计。Vercel 自带一些观测功能，也有专门的第三方服务。现在你的流量不大，先养成“每次发内容后看一眼 Logs”的习惯；以后流量大了再考虑接入监控服务。
真出事时人会慌，所以要提前把顺序定好，写进故障手册，到时候照着做：
下午你会把这套流程完整走一遍：故意制造一个错误，在日志里把它找出来。明天给网站绑定你自己的域名。
查看你的历史窗口
登录 Neon 控制台，打开 dongge-web 用的项目，在项目设置里找到历史保留（history）相关的设置，记下你的套餐能回到多久以前。再打开侧边栏 Branches，看清哪个分支是正式库在用的（通常叫 main 或 production）。
演练准备：造一条测试数据
打开线上网站的提问箱，提交一条内容为“【演练】DAY68 备份恢复测试”的提问。记下提交后的时间（精确到分钟），然后等 2 分钟。
模拟误删
在 Neon 的 SQL 编辑器里选正式分支，先查，再删。永远先用 SELECT 确认 WHERE 条件只命中你想删的那一条：
SELECT id, content, status, "createdAt" FROM "Question" WHERE content = '【演练】DAY68 备份恢复测试';
DELETE FROM "Question" WHERE content = '【演练】DAY68 备份恢复测试';从过去的时间点建分支
侧边栏 Branches，点 New branch：父分支选正式分支，名字填 drill-restore，内容选 Past data，时间选“提交之后、删除之前”（第 2 步记下的时间加 1 分钟），点 Create。注意界面上的时区。
在分支里找回数据
在 SQL 编辑器顶部把分支切换到 drill-restore，运行：
SELECT id, content, nickname, status, answer, "createdAt" FROM "Question" WHERE content LIKE '【演练】%';放回正式库，然后清理
把 SQL 编辑器切回正式分支，用刚才复制的值插回去（id 如果是数字就不要加引号，是字符串就加单引号）：
INSERT INTO "Question" (id, content, nickname, status, answer, "createdAt")
VALUES ('复制来的id', '【演练】DAY68 备份恢复测试', NULL, 'PENDING', NULL, '复制来的时间');确认能查到后，这条演练数据就完成使命了，按第 3 步的方法再删掉。最后在 Branches 里点 drill-restore 那一行右边的三个点，选 Delete 删除分支。
安装 libpq，做一份 pg_dump 备份
按上午的命令安装 libpq 并配置 PATH。在 Neon 控制台点 Connect，关掉连接池选项，复制直连的连接串（地址里没有 -pooler）。然后运行上午的导出命令，再验证：
ls -lh ~/backups/dongge-web
pg_restore --list ~/backups/dongge-web/dongge-web-$(date +%Y%m%d).dump | head -20故意制造一个错误（只在预览环境）
cd ~/code/dongge-web
git switch main
git pull
git switch -c chore/day68-error-drill
mkdir -p app/boomdongge-web/app/boom/page.tsx
import { connection } from "next/server";
export default async function BoomPage() {
await connection();
throw new Error("DAY68 演练：故意制造的错误");
}await connection() 告诉 Next.js 这个页面要等真实的访问请求来了再渲染，否则它会在构建时就尝试渲染这个页面，一抛错构建就失败了。然后推送这个分支（不开 PR、不合并）：
git add app/boom/page.tsx
git commit -m "chore: DAY68 错误演练页（不合并）"
git push -u origin chore/day68-error-drill在预览部署里触发错误
打开 Vercel 项目的 Deployments，找到这个分支的预览部署，等它构建完成后打开，在网址后面加上 /boom。记下页面上显示的错误编号和当前时间。
在 Logs 里找到它
打开 Vercel 项目侧边栏的 Logs：Environment 选 preview，Status Code 选 500，时间选最近 30 分钟；或者直接在搜索框搜 DAY68。点开那条请求，读右侧的日志内容。
app/boom/page.tsx 的堆栈；日志里如果带有 digest，确认它和页面上的错误编号一致。清理演练分支
git switch main
git branch -D chore/day68-error-drill
git push origin --delete chore/day68-error-drill-D 表示强制删除没合并过的本地分支；第三行删除 GitHub 上的远程分支。这个页面永远不会进入正式网站。
补日志、写故障手册，然后回答今天的问题
找到 ops 标签的 issue，新建分支 feat/error-logging。把“问 Claude”第 2 条提示词发给它，让它给数据库操作加上规范的错误日志，你按“没有个人信息、没有密钥、每条都有 [模块名]”审查。同时自己写一份 docs/runbook.md：
dongge-web/docs/runbook.md
# 故障手册（dongge-web）
## 我的服务
- 网站：Vercel 项目 dongge-web。Logs 在项目侧边栏；Hobby 版日志只保留 1 小时，时间是 UTC
- 数据库：Neon 项目（新加坡），正式分支 main，历史窗口 6 小时（免费版）
- 图片：Vercel Blob
- AI：Anthropic 控制台，已设置每月用量上限
## 线上出错时
1. 记录：时间、网址、操作、错误编号、截图、能否重现
2. Vercel → Logs：Environment 选 production，Status Code 选 5xx，时间选出错前后；或搜索错误编号
3. 读报错第一行，在堆栈里找第一个指向自己代码的文件和行号
4. 如果是刚合并的改动引起的：项目首页生产部署卡片 → Instant Rollback 先回退
5. 新分支修复，先写能重现问题的测试，走 PR 合并
6. 修好后点 Undo Rollback，恢复自动部署
7. 在本文件末尾记一笔事故记录
## 数据出问题时
- 误删几条（6 小时内）：Branches → New branch → Past data 建分支，查出旧数据，INSERT 回正式分支，删掉临时分支
- 整个库被改坏（6 小时内）：Backup & Restore → Restore from history。之后的新数据会一起回退，先想清楚
- 超过 6 小时：用最近一次 pg_dump 文件，pg_restore 到新分支，再把需要的数据拷回
## 备份记录
| 日期 | 方式 | 文件 | 验证方式 |
| 2026-xx-xx | pg_dump | dongge-web-2026xxxx.dump | pg_restore --list |
## 事故记录
（暂无）提交、开 PR（描述写 Closes #编号）、合并。最后用一句话回答：线上出错时，你第一步去哪里看？明天给网站绑定你自己的域名。
source ~/.zshrc 并检查 ~/.zshrc 末尾那一行；版本不匹配就运行 brew upgrade libpq。-pooler 的连接池地址。回 Neon 控制台点 Connect，关掉连接池选项，换直连地址。线上出错时，你第一步去哪里看？
先花一分钟记录现场（时间、网址、错误编号、能否重现），然后第一个去看的是 Vercel 项目侧边栏的 Logs：环境选 production，状态码选 5xx，时间选出错前后，或者直接搜错误编号，找到那次请求的完整报错和堆栈。如果日志显示是刚合并的改动引起的，先用 Instant Rollback 回到上一个部署止血，再在新分支上修。部署本身失败的话，看的是部署详情里的构建日志。
粉丝下午 3 点说提问箱提交失败了，你晚上 7 点才看到。Vercel 日志还能找到吗？该怎么办？
多半找不到了，Hobby 版运行时日志只保留 1 小时。办法是让问题重现：问粉丝具体时间、用的什么手机和浏览器、页面上显示的提示或错误编号，自己按同样的步骤操作一遍，一边操作一边开着 Logs 的 Live 模式看。以后可以养成发完内容后看一眼日志的习惯，并在关键操作里用 console.error 打出带模块名的日志，出问题时更容易定位。
误删了一条 look，和一次迁移把整张 Look 表搞坏，恢复方式有什么不同？
误删一条：从删除之前的时间点建一个 Neon 分支，在分支里查出这条 look，用 INSERT 放回正式分支，其他数据都不受影响。整张表被迁移搞坏：用 Backup & Restore 把正式分支整体回退到迁移之前，Neon 会自动保留一个回退前的备份分支，但这个时间点之后的所有新数据都会一起回退，事后可能要从备份分支里把新提问拷回来。两种都要在历史窗口内；超出窗口就只能用 pg_dump 备份文件恢复。
dig 和 curl -I 验证解析、跳转和 HTTPS 是否生效。BETTER_AUTH_URL 和 SITE_URL，并确认登录、分享卡片、sitemap 在新域名下都正常。DAY 03 第一次上线时，你学过一次网页访问的全过程。今天把其中“域名和 DNS”这一段学透，因为你要亲手配置它。先用手机通讯录打个比方：服务器在网络上的真实地址是一串数字（IP 地址，比如 76.76.21.21），就像电话号码，难记；域名（比如 example.com）就像通讯录里的名字，好记。DNS（域名系统）就是全世界共用的那本“通讯录”，负责把名字翻译成号码。
你在手机上输入网址后，查号过程大致是这样的：浏览器先看自己最近有没有查过（缓存）；没有就问手机系统；再问网络运营商或公共 DNS 服务器（叫递归解析器）；递归解析器如果也不知道，就从“根服务器”问起，根服务器告诉它“.com 的事去问 .com 的服务器”，.com 的服务器再告诉它“example.com 归哪几台服务器管”（这几台叫权威服务器）；最后权威服务器给出真正的答案。答案会被各级缓存一段时间，下次就快了。
现在你的网站地址是 dongge-web.vercel.app，它是 Vercel 送的子域名。放进各平台简介，自己的域名有三个好处：更好记，也更像一个正式的品牌；以后就算换掉 Vercel，域名不变，粉丝收藏的链接不会失效；Vercel 官方也提到，从中国大陆访问时 .vercel.app 这类地址可能被限制，自己的域名被限制的可能性更小，但官方同时说明无法保证大陆的访问速度和可用性。你的小红书观众很多在大陆，这一点要心里有数。
先看懂域名的结构。域名要从右往左读，像地址从“国家、城市”读到“门牌号”：www.example.com 里，最右边的 com 是顶级域；example 是你买下的那一段，example.com 合起来就是你拥有的域名，也叫根域名；最左边的 www 是你在自己的域名下开的子域名。买下根域名以后，子域名想开多少开多少，不用再花钱，比如以后做 Go 服务时可以开一个 api.example.com。
在“通讯录”里，一个域名下面可以有多条记录，每条有类型、名字、值和 TTL。今天会用到这几种：
| 类型 | 作用 | 比喻 | 今天的例子 |
|---|---|---|---|
| A | 把名字指向一个 IPv4 地址 | 名字后面直接写电话号码 | 根域名 example.com 指向 Vercel 给的 IP |
| CNAME | 把名字指向另一个名字 | “找他请打给某某” | www.example.com 指向 Vercel 给的一个专属名字 |
| TXT | 存一段文字，常用来证明“这个域名是我的” | 在门上贴一张写着暗号的纸条 | 域名被其他 Vercel 账号用过时，用它验证所有权 |
| NS | 指定这个域名由哪几台权威服务器管理 | 这本通讯录放在谁家 | 一般不用改，除非选择 Nameserver 方式 |
| MX | 指定收邮件的服务器 | 信件寄到哪个邮局 | 如果你用这个域名收邮件，千万别误删 |
TTL（Time To Live，存活时间）是每条记录被缓存多久，单位是秒。TTL 为 3600 意味着各地的解析器会把答案记住一小时，一小时内你改了记录，有些人看到的还是旧的。这就是为什么改 DNS 后有时要等一会儿才生效。
还有一个关键规则：根域名（也叫顶级的“裸域名”，比如 example.com，不带任何前缀）按 DNS 规范不能设置 CNAME，只能用 A 记录；子域名（比如 www.example.com）可以用 CNAME。Vercel 文档因此给出两种配置：根域名用 A 记录，子域名用 CNAME 记录，而且每个项目的 CNAME 值都是专属的，形如一串字符加 .vercel-dns-017.com。具体的值以 Vercel 域名页面上显示的为准，不要照抄别人的。
域名一旦印进视频、放进简介，就很难再换，所以值得花一小时认真想。几条原则：
你可以沿着“名字加特征”的思路列候选，比如把“三岁”写成数字 3 放在名字后面，或者用名字的拼音组合。这些只是思路示范，能不能注册、价格多少，要你自己去查。
卖域名的公司叫注册商。包括 Vercel 在内，很多平台都能买域名。本课不推荐具体商家，你按下面的标准自己比较：
Vercel 的操作入口在项目的 Settings 里，侧边栏选 Domains，点 Add Domain，输入你的域名。如果你输入的是根域名（example.com），Vercel 会建议同时添加 www 版本，接受它：这样无论粉丝输入带不带 www，都能打开。
两个里面选哪个当“主域名”、另一个跳转过去？Vercel 文档推荐用 www 当主域名，让根域名跳转到 www。原因是 www 可以用 CNAME，Vercel 能在 DNS 层面灵活地调度流量（比如遇到攻击时切换线路），可靠性更好；根域名只能用 A 记录写死一个 IP。文档也说明，反过来让 www 跳到根域名同样可以用，只是 Vercel 能做的调度少一些。Chrome 等浏览器会在地址栏里隐藏 www，所以对外观影响不大。
添加后，Vercel 会在域名卡片上显示需要你去注册商那里添加的记录，通常是：
| 类型 | 名字（Name / Host） | 值（Value） |
|---|---|---|
| A | @（代表根域名本身） | 卡片上给出的 IP，文档举例为 76.76.21.21 |
| CNAME | www | 卡片上给出的专属地址，形如一串字符加 .vercel-dns-017.com |
然后登录注册商，找到 DNS 管理，删掉和这两个名字冲突的旧记录（很多注册商会默认放一条指向“停放页”的 A 记录或 www 的 CNAME），再按卡片添加这两条。不同注册商的“名字”一栏写法不同：有的写 @ 和 www，有的要写完整的 www.example.com，看清它的说明。保存后回到 Vercel，等待验证，状态变成配置正确就好了。如果这个域名曾被别的 Vercel 账号用过，Vercel 会要求你额外加一条 TXT 记录证明所有权。
Vercel 还提供另一种方式：把域名的 NS 记录改成 Vercel 的服务器，整个“通讯录”交给 Vercel 管。官方文档提醒，改之前要先把已有的记录（尤其是收邮件用的 MX 记录和各种验证用的 TXT 记录）复制到 Vercel，否则邮箱会收不到信。对你来说，只加 A 和 CNAME 两条最简单，其他记录都不受影响。
最后设置跳转：在 Domains 里对根域名点 Edit，在 Redirect to 下拉框里选 www 域名，保存。
HTTPS 是加密版的 HTTP。它做两件事：加密，路上的人（比如公共 Wi-Fi 的管理者）看不到粉丝提交了什么；身份证明，浏览器通过证书确认“你连的真的是这个域名的服务器”，而不是冒充的。浏览器地址栏的锁头，就是证书有效的标志。证书要由受信任的机构签发、定期续期，以前要自己申请，现在 Vercel 会在域名配置正确后自动申请和续期，你不用做任何事，一般几分钟内生效。
全站 HTTPS 还有一个细节：页面是 HTTPS，但页面里引用的图片、脚本如果是 http:// 开头，浏览器会报“混合内容”（Mixed Content），可能直接拦截这些资源。你的图片都在 Vercel Blob，本来就是 https；但以前手写的外链、旧官网的图片地址，要检查一遍。
域名是整个网站的“门牌号”，门牌换了，写着旧门牌的地方都要改：
BETTER_AUTH_URL：Better Auth 用它作为登录服务的基础地址，文档说明没有显式设置 baseURL 时就读这个环境变量，并且强烈建议明确设置。在 Vercel 项目 Settings 的 Environment Variables 里，把 Production 环境的值改成新的主域名（比如 https://www.example.com）。环境变量改了只对新部署生效，所以改完要重新部署一次。trustedOrigins：如果你在 lib/auth.ts 里配置过它，把新域名加进去。以后登录后台固定用主域名，不要再用 vercel.app 地址登录。lib/site.ts 的 SITE_URL：DAY 66 你把网站地址集中放在这里，现在只改这一行，metadataBase、sitemap、robots 就都跟着变了。明天做全项目代码审查，把上线前最后的高优先级问题清掉。
列候选域名并打分
在本子上列 3 到 5 个候选，每个按五项打分（每项 1 到 3 分）：
| 候选 | 口播好记 | 短 | 无歧义 | 和平台名一致 | 后缀合适 | 总分 |
| 候选一 | | | | | | |
| 候选二 | | | | | | |
| 候选三 | | | | | | |把总分最高的两个念给一位朋友听，请他写下来，看他拼得对不对。
查可注册性，比较价格，自己决定
在你选的注册商那里搜索候选域名，对每个可注册的记下三样：首年价、续费价、是否含隐私保护。买不买由你决定。如果暂时不买，用下面的命令查几个已有网站练习 DNS，等买了再回来做第 4 到 11 步：
dig +short vercel.com A
dig +short www.vercel.com CNAME买完先做安全设置
如果决定购买：在注册商的账户里开启两步验证；确认隐私保护已开启；打开自动续费并检查付款方式；把到期日和注册商名字记进 docs/runbook.md。结账前逐项看清订单，取消不需要的附加服务。
在 Vercel 添加域名
打开 Vercel 的 dongge-web 项目，Settings，侧边栏 Domains，点 Add Domain，输入你的根域名（比如 example.com）。接受添加 www 的建议，选择 www 作为主域名、根域名跳转过去（也可以反过来，按你的偏好）。
在注册商添加 DNS 记录
登录注册商的 DNS 管理，先删除名字为 @ 和 www 的旧 A 记录和 CNAME 记录（如果有），不要动 MX 和 TXT 记录。然后按 Vercel 卡片上的值添加：
类型 名字 值
A @ （复制 Vercel 卡片上的 IP）
CNAME www （复制 Vercel 卡片上的专属地址）TTL 用默认值即可，保存。
用 dig 验证解析
等几分钟，在终端运行（把 example.com 换成你的域名）：
dig +short example.com A
dig +short www.example.com CNAME
dig +short www.example.comdig 是 macOS 自带的 DNS 查询工具，+short 表示只显示答案。第一行应该返回 Vercel 给的 IP；第二行应该返回 Vercel 给的专属地址；第三行会先显示那个专属地址，再显示它最终对应的 IP。
等 Vercel 验证通过
回到 Vercel 的 Domains 页面刷新，两个域名的状态都变成配置正确（Valid Configuration），证书自动签发。用浏览器打开 https://www.example.com，看到你的首页，地址栏有锁头。
设置跳转
在 Domains 里对非主域名（比如根域名）点 Edit，在 Redirect to 里选主域名，保存。
用 curl 验证跳转和 HTTPS
curl -I http://www.example.com
curl -I https://example.com
curl -I https://www.example.comcurl -I 只请求响应头，不下载页面内容。第一行应该看到 3 开头的状态码和指向 https 的 location；第二行应该看到 3 开头的状态码和指向 www 的 location；第三行应该是 200。
更新 BETTER_AUTH_URL 并重新部署
Vercel 项目 Settings，Environment Variables，找到 BETTER_AUTH_URL，把 Production 环境的值改成 https://www.example.com（你的主域名，结尾不要斜杠），保存。然后到 Deployments，对最新的生产部署点三个点，选 Redeploy。同时打开 lib/auth.ts，看有没有 trustedOrigins，有的话记下来，下一步一起改。
更新 SITE_URL，走 PR 上线
cd ~/code/dongge-web
git switch main
git pull
git switch -c chore/custom-domain把“问 Claude”第 2 条提示词发给它，确认它列出的地方后再让它改：lib/site.ts 的 SITE_URL、lib/auth.ts 的 trustedOrigins（如果有）、README 的线上地址。审完 diff 后提交、推送、开 PR（描述写 Closes #编号）、合并。部署完成后逐项验证：
https://www.example.com/sitemap.xml，所有网址都是新域名。https://www.example.com/quiz/result/thai 发到聊天软件，卡片正常。检查混合内容，请大陆的朋友帮忙测试
grep -rn "http://" app components lib除了 http://localhost 这类本地地址，其他 http:// 开头的外链都改成 https。再在浏览器里逐页打开，看开发者工具 Console 有没有 Mixed Content 警告。最后请一位在中国大陆的朋友用手机打开新域名，记下打开速度和有没有打不开的页面，写进故障手册。然后回答今天的核心问题：你打开网站时，DNS 解析起了什么作用？
dig 看实际解析结果。常见原因：旧的冲突记录没删；TTL 还没过期；名字一栏写法不对，有的注册商会自动在后面补上域名，你写了 www.example.com 就变成了 www.example.com.example.com。BETTER_AUTH_URL 没改，或者改了但没有重新部署；lib/auth.ts 里如果写死了 trustedOrigins，新域名没加进去。你打开网站时，DNS 解析起了什么作用？
浏览器只能按 IP 地址去连接服务器，而我输入的是域名。DNS 负责把域名翻译成 IP：浏览器先查自己和系统的缓存，没有就问递归解析器，解析器从根服务器问到 .com 的服务器，再问到我的域名的权威服务器，拿到答案。对 www.example.com 来说，答案先是一条 CNAME，指向 Vercel 给的专属地址，再由 Vercel 的 DNS 返回最合适的 IP。拿到 IP 后浏览器才能建立 HTTPS 连接、发请求、收到页面。解析结果会按 TTL 缓存，所以第二次打开更快，改记录后也要等缓存过期。
为什么根域名用 A 记录，www 用 CNAME？
DNS 规范不允许根域名设置 CNAME，所以根域名只能用 A 记录直接指向 IP。www 是子域名，可以用 CNAME 指向 Vercel 给的专属名字，Vercel 可以在背后随时调整这个名字对应的 IP，遇到攻击或线路问题时能灵活切换，不需要我改任何记录。这也是 Vercel 推荐 www 当主域名、根域名跳转过去的原因。
换域名后哪些地方要跟着改？漏改 BETTER_AUTH_URL 会怎样？
要改：Vercel 生产环境的 BETTER_AUTH_URL（并重新部署）、lib/auth.ts 里的 trustedOrigins（如果配置过）、lib/site.ts 的 SITE_URL、README 和故障手册里的地址。漏改 BETTER_AUTH_URL 的话，Better Auth 还以旧地址为准，在新域名下登录时可能因为来源不匹配被拒绝，或者登录后回调跳回旧网址，Cookie 也可能设在错误的域名上，表现就是“登录不上后台”。
/code-review 按目录分批审查整个项目，说出默认审查范围、effort 等级和 --fix 的区别。过去五天你给网站加了性能优化、分享卡片、限流、错误页、日志和新域名，改动分散在十几个 PR 里。每个 PR 单独看都没问题，但合在一起会不会有漏洞？更早以前写的代码（DAY 43 的提问箱、DAY 48 的后台）当时你的水平和现在不一样，会不会有当时没意识到的问题？这就像装修完交房前的“验房”：每个工种都说自己干完了，业主还是要从头到尾走一遍。
测试和审查是两种互补的检查。测试只能发现你想到要测的问题：你写了“超过 300 字被拒绝”的测试，它就守住这一条，但你没想到的漏洞它不会告诉你。代码审查是让另一双眼睛读代码，专门找你没想到的问题。Claude 的审查速度快、覆盖面广，但它也会误报：有时把不是问题的地方说成问题，有时建议一些对你的项目没必要的改动。所以今天你的角色是“审查意见的审查者”：它负责找，你负责判断、排优先级、决定修不修。
/code-review 是 Claude Code 内置的审查命令，别名是 /review。按官方文档，它有几个要点：
/code-review，它审查你当前分支上比远程多出来的提交，加上还没提交的修改。如果你在干净的 main 上运行，就没什么可审的。main...某个分支 这样的比较范围。今天要审整个项目，就按目录一个个传路径进去。low、medium、high、xhigh、max。文档说明 low 和 medium 只报告最有把握的问题，误报少；high 到 max 覆盖更广，但可能包含它不太确定的问题。不写等级时会沿用你上一次输入的等级。ultra 是云端深度审查：会在云端跑更深入的审查，可能需要额外的用量额度，界面会先让你确认。今天用不到，看到计费确认就取消。--fix 会直接改代码：审查完自动把修改应用到你的工作区。文档提醒，后台审查用 --fix 做的修改，/rewind 撤销不了，只能用 Git 回退。今天不用它，因为你要先判断每条意见对不对。--comment：把审查结果作为评论发到 GitHub 的 PR 上，以后审 PR 时可以用。审查在后台运行，有自己独立的上下文，不会把你的对话塞满，完成后结果会出现在对话里。在桌面 App 里，结果会显示成一个问题列表，每条有文件位置、一句话总结和类别标签（比如 correctness，正确性）。审查也会读你的 CLAUDE.md，DAY 64 写的“后台每个 Server Action 开头都要检查登录”这类规则，会成为它的审查标准之一，这就是当初把规则写具体的回报。
另外两个相关工具：桌面 App 的 diff 视图右上角有一个 Review code 按钮，可以审查 Claude 刚做的改动；/security-review 专门检查当前分支改动里的安全问题。今天主要用 /code-review。
/code-review 时留意界面上的提示，以官方文档为准。为什么不一次审整个项目？一次塞进去的代码太多，审查的注意力会被摊薄，重要的问题反而可能漏掉。按功能分批，每批一个目录，Claude 能看得更仔细，你也更容易消化结果。建议这样分：
| 批次 | 路径 | 重点 |
|---|---|---|
| 1 | app/ask、lib/rate-limit.ts、lib/validations.ts | 公开入口：输入校验、限流、蜜罐 |
| 2 | app/admin、app/api | 每个 Server Action 和 Route Handler 是否检查登录；删除和修改是否安全 |
| 3 | app/quiz、lib/quiz-results.ts | 计分逻辑、同分处理、分享页 |
| 4 | app/page.tsx、app/world、app/links | 数据查询、空状态、图片、点击统计 |
| 5 | lib、prisma/schema.prisma | 数据模型、索引、密钥的读取方式 |
每批运行一次，比如 /code-review high app/admin。路径按你项目的实际目录改。effort 选 high：上线前宁可多看几条可能的问题，再由你来筛。
读每一条审查结果时，先做三件事：点开它指的文件和行号，亲眼看那段代码；用自己的话把问题复述一遍，比如“删除 look 的函数没有先确认是不是管理员在操作”，复述不出来就说明你还没看懂，先问 Claude；再想一想这个问题在真实使用中会怎样出现，是粉丝会碰到，还是只有恶意的人专门构造请求才会碰到。做完这三件事再记进审查记录，后面分级时就不会糊里糊涂。
审查可能报出几十条问题，全修既不现实也没必要。分级的目的，是把有限的时间花在真正要命的地方。
| 级别 | 含义 | 你的项目里的例子 | 处理 |
|---|---|---|---|
| P0 | 安全漏洞、数据会丢失或泄露、上线就会崩 | 某个后台 Server Action 没检查登录，谁都能删 look；密钥出现在客户端代码里；待审核的提问能绕过审核直接显示 | 立刻修，不修不上线 |
| P1 | 主要功能出错、成本可能失控、体验明显受损 | 看板在没有数据时报错；某个结果的分享页打不开；文案助手出错时会无限重试 | 上线前修 |
| P2 | 代码整洁、命名、可以优化但不影响使用 | 组件太长可以拆分；有两段相似代码可以合并；变量名不够清楚 | 记成 issue，上线后再说 |
判断时问自己三个问题。第一，真的会发生吗？能不能说出触发它的具体步骤？第二，发生了影响谁、有多严重？是影响所有粉丝，还是只在你后台某个很少用的角落？是丢数据，还是按钮颜色不对？第三，修它要改多少？改动大的修复本身也有风险，上线前夕要格外谨慎。一条意见如果“会发生、影响大、好修”，就是 P0 或 P1；“不太会发生、影响小”，就放 P2。
对拿不准的意见，不要急着让 Claude 修，先让它证明问题存在。有两种证明方式：给出能复现的具体操作步骤（打开哪个页面、输入什么、会看到什么错误）；或者写一个现在会失败的测试。能证明的就是真问题；证明不了、或者复现步骤根本走不通的，很可能是误报。
“先写一个会失败的测试，再修代码”是一个很好的习惯。它有三个好处：证明问题真的存在，而不是想象出来的；修完后测试变绿，证明真的修好了，而不是“看起来改了”；这个测试会一直留在项目里，以后谁不小心把问题改回来，CI 会立刻报警。这比“改完点一点页面看看”可靠得多。
拒绝一条意见也要有理由，写进审查记录。常见的合理理由：这个场景在你的项目里不会发生（比如后台只有你一个管理员，不需要复杂的权限分级）；修复成本远大于收益；它建议引入新的库，违反 CLAUDE.md 的约定。能说清为什么不改，说明你真的看懂了这段代码。
测试不是越多越好，而是要守住“坏了损失最大”的地方。对照需求文档的验收标准，你的关键流程有：粉丝提交提问并被限流保护；未登录不能进后台、不能调用后台操作；三个测试结果页和分享图都存在；不存在的网址返回 404。DAY 51 和 52 已经写过一部分，今天补上正式版新增的部分。纯函数用 Vitest：
dongge-web/lib/quiz-results.test.ts
import { describe, expect, it } from "vitest";
import { QUIZ_RESULTS, getQuizResult, isWorldSlug } from "./quiz-results";
describe("quiz-results", () => {
it("三个世界都有完整的结果文案", () => {
expect(Object.keys(QUIZ_RESULTS)).toEqual(["gentleman", "street", "thai"]);
for (const result of Object.values(QUIZ_RESULTS)) {
expect(result.name.length).toBeGreaterThan(0);
expect(result.feeling.length).toBeGreaterThan(0);
expect(result.line.length).toBeGreaterThan(0);
}
});
it("认识的 slug 返回对应结果", () => {
expect(getQuizResult("street")?.feeling).toBe("心动");
});
it("不认识的 slug 返回 null", () => {
expect(getQuizResult("abc")).toBeNull();
expect(isWorldSlug("toString")).toBe(false);
});
});逐段解释：第一个测试检查三个世界一个不少、每条文案都不是空的，以后有人改文案时手滑删空了，测试会报警。第二个测试检查正常情况。第三个测试检查异常输入，特别测了 "toString"：它是每个 JavaScript 对象都自带的属性名，如果判断 slug 时写成 slug in QUIZ_RESULTS，它会被误判为合法。这种“刁钻输入”正是审查和测试要守住的边界。
跨页面的流程用 Playwright，模拟真人打开浏览器：
dongge-web/tests/launch.spec.ts
import { test, expect } from "@playwright/test";
test("不存在的网址返回 404 和自定义页面", async ({ page }) => {
const response = await page.goto("/this-page-does-not-exist");
expect(response?.status()).toBe(404);
await expect(page.getByRole("heading", { name: "这一页走丢了" })).toBeVisible();
});
test("测试结果页有标题和专属分享图", async ({ page }) => {
await page.goto("/quiz/result/street");
await expect(page.getByRole("heading", { name: "街头" })).toBeVisible();
await expect(page.locator('meta[property="og:image"]')).toHaveAttribute(
"content",
/opengraph-image/
);
});
test("未登录访问后台会被带到登录页", async ({ page }) => {
await page.goto("/admin");
await expect(page).toHaveURL(/login/);
});逐段解释：page.goto 会返回服务器的响应，status() 拿到状态码，确认真的是 404，而不是“显示了 404 页面但状态码是 200”，后者会让搜索引擎误以为这是个正常页面。getByRole("heading", { name: ... }) 按“标题元素加文字”找元素，比按 CSS 类名找更稳定。locator('meta[property="og:image"]') 找到分享图标签，toHaveAttribute 用正则检查它的地址里包含 opengraph-image。最后一个测试确认未登录时被带到登录页；如果你的登录页网址不含 login，把正则改成你的实际地址。DAY 52 如果已经写过类似的测试，就不要重复。
DAY 53 你配置了 CI：每次推送自动跑类型检查、测试和构建。今天的完成标准是“CI 全部通过，没有未处理的高优先级问题”，这两条缺一不可。纪律只有一句话：CI 是红的，就不合并。哪怕你觉得“只是个不相关的测试挂了”，也要先搞清楚原因，因为上线前最怕的就是带着一个“以为没关系”的问题上线。
GitHub 可以把这条纪律变成硬规则：在仓库设置里给 main 分支加保护规则，要求“状态检查通过后才能合并”，CI 不绿，合并按钮就是灰的。这一步是可选的，GitHub 的设置界面经常调整，按官方文档找当前的入口。明天就是正式发布日，今天清干净，明天才能安心按清单发布。
准备：干净的 main 和一份基线
cd ~/code/dongge-web
git switch main
git pull
git status
npm run lint
npx tsc --noEmit
npm test
npx playwright test
npm run build记下哪些命令通过、哪些失败。如果现在就有失败的，它自动成为今天的第一个 P1。
git status 显示工作区干净，你知道当前每项检查的状态。建一份审查记录
dongge-web/docs/review-day70.md
# 上线前全面审查（DAY 70）
| # | 批次 | 文件:行 | 问题（一句话） | 分级 | 判断理由 | 处理 | issue / PR |
| 1 | | | | | | | |“处理”一栏填：修复、记为 P2、误报（拒绝）。
第 1 批：公开入口
在 Claude Code 里依次输入（路径按你的项目改）：
/code-review high app/ask
/code-review high lib/rate-limit.ts等结果出现，把每一条抄进审查记录的“问题”一栏，先不分级。等待时可以接着准备下一批。
第 2 到 5 批
/code-review high app/admin
/code-review high app/api
/code-review high app/quiz
/code-review high app/world
/code-review high lib
/code-review high prisma/schema.prisma全部记进审查记录。第 2 批（后台）最重要，每条都要仔细看。
给每条问题分级
对每条问三个问题（会不会发生、影响多大、修的代价），填上 P0、P1 或 P2，并在“判断理由”里写一句话。拿不准的先标问号。
验证拿不准的意见
对标了问号的每一条，用“问 Claude”第 1 条提示词要求它证明。能给出复现步骤或失败测试的，按真实影响定级；证明不了的，标为“误报（拒绝）”，理由写清楚。
建优先级标签，把 P0 和 P1 写成 issue
gh label create P0 --color B60205 --description "上线前必须修：安全或数据"
gh label create P1 --color D93F0B --description "上线前修：主要功能或成本"每个 P0 和 P1 建一条 issue：标题写结果（比如“删除 look 的 Server Action 必须检查登录”），正文写问题、复现步骤、验收标准（包括“有一个能复现问题的测试”）。用 DAY 64 学的 --body-file 方式创建，贴上 P0 或 P1 标签，再加一个分类标签（security、test 等）。P2 可以合并成一条“上线后优化清单” issue。
一次修一个：先红后绿
从 P0 开始，每个 issue 一个分支：
git switch main
git pull
git switch -c fix/编号-简短描述把“问 Claude”第 2 条提示词发给它。它会先写测试并运行给你看失败（红），再改代码运行给你看通过（绿）。你审查两样东西：测试是不是真的在测这个问题；代码改动是不是只动了相关的地方。通过后提交、推送、开 PR，描述写 Closes #编号，CI 绿了再合并。
补正式版的关键测试
新建分支 test/launch-coverage，用“问 Claude”第 3 条提示词让它列出没有测试覆盖的关键流程。你确认清单后，让它写测试，至少包括上午的 lib/quiz-results.test.ts 和 tests/launch.spec.ts（DAY 51、52 已经覆盖的跳过）。本地运行：
npm test
npx playwright test推送，让 CI 全绿后合并
提交测试分支、开 PR、等 CI。如果本地通过而 CI 失败，打开 GitHub 上这次运行的日志，找到第一个报错（DAY 53 练过），常见原因是 CI 里缺环境变量或 Playwright 浏览器没装。修好再推，全绿后合并。
复查修过的目录
回到最新的 main，对出过 P0 和 P1 的目录再跑一次审查，确认问题已经解决、没有引入新问题：
/code-review medium app/admin这次用 medium，只看它最有把握的问题。
最终确认
gh issue list --label P0 --state open
gh issue list --label P1 --state open
gh run list --branch main --limit 3前两条应该没有输出（没有打开的 P0 和 P1），第三条最近的运行都是成功状态。把审查记录的“处理”一栏补全，提交 docs/review-day70.md。明天按上线检查清单逐项检查，正式发布。
/code-review high app/admin。--fix 修改不在对话的检查点里。用 git diff 看改了什么，确认都不要后用 git restore . 撤销。今天不要用 --fix。.env。检查 GitHub 仓库的 Secrets 是否配齐、工作流里有没有安装 Playwright 浏览器的步骤，读日志里的第一个报错。CI 全部通过，没有未处理的高优先级问题。请展示结果，并说明你是怎么确认的。
展示三样东西：gh run list --branch main --limit 3 的输出，最近的运行都是成功；gh issue list --label P0 --state open 和 gh issue list --label P1 --state open 都没有输出；docs/review-day70.md 里每一条问题都有分级和处理结果，P0 和 P1 都对应一个已合并的 PR，P2 汇总进了一条上线后优化的 issue。确认方式不是“我觉得修好了”，而是每个修复都有测试从红变绿，并且对修过的目录复查过一次。
说出你拒绝的一条审查意见，以及理由。
答案来自你自己的审查记录。一个合理的例子：审查建议给后台加“角色和权限分级”，区分编辑和超级管理员。拒绝理由是需求文档写明后台只有东哥一个管理员，现在做权限分级会增加复杂度和出错的地方，却没有实际收益；将来真有多人协作时再做。拒绝的理由要基于项目的实际情况和需求文档，而不是“懒得改”。
修 bug 前为什么要先写一个会失败的测试？
第一，证明问题真的存在，而不是审查的误报；第二，修完后测试变绿，证明修复真的起作用，而不是“看起来改了”；第三，这个测试会一直留在项目里，以后任何改动如果让问题复发，CI 会立刻失败，问题不会悄悄回来。如果先修后写测试，很难确定测试本身是对的，因为你从没见过它失败。
git tag 给正式版打上 v1.0.0 标签，并用 gh release create 发布版本说明。飞行员起飞前，不管飞了多少年，都会拿着检查单一项项念、一项项确认。不是因为他们记不住，而是因为人在紧张和兴奋的时候最容易漏掉“显而易见”的事。发布日就是这样的时刻：你会激动、会着急，很可能忘了删测试数据，或者忘了链接页上还留着 example.com 的占位链接。
今天的规则只有两条。第一，发布日不加新功能，这叫“代码冻结”：只修清单检查出来的问题，而且只修小的（错别字、链接、文案）；任何“顺手加个小功能”的想法都记进 issue，发布后再说。原因很简单：每一行新代码都可能带来新问题，而你今天没有时间给它做完整的测试和审查。第二，每一项打勾前必须亲手验证过，不能凭“应该没问题”打勾。
下面这份清单汇总了前 70 天的所有关键点，分成 10 组。下午你会把它复制成 docs/launch-checklist.md，按你项目的实际情况增删，然后一项项检查。每一项后面都写了检查方法。
dongge-web/docs/launch-checklist.md
# 上线检查清单（v1.0.0）
检查人：东哥 日期：2026-xx-xx 规则：打勾前必须亲手验证
## A. 代码与构建
- [ ] main 是最新的，没有打开的 P0 / P1：gh issue list --label P0、gh issue list --label P1
- [ ] CI 最近一次运行成功：gh run list --branch main --limit 1
- [ ] 本地全套检查通过：npm run lint、npx tsc --noEmit、npm test、npx playwright test、npm run build
- [ ] 没有遗留的调试输出：grep -rn "console.log" app components lib
- [ ] 依赖没有高危漏洞：npm audit（看 high 和 critical，看不懂就请 Claude 解释）
## B. 密钥与环境变量
- [ ] .env 没有被 Git 跟踪：git ls-files | grep -i env（只允许出现 .env.example）
- [ ] Vercel 生产环境 5 个变量齐全：DATABASE_URL、BETTER_AUTH_SECRET、BETTER_AUTH_URL、
BLOB_READ_WRITE_TOKEN、ANTHROPIC_API_KEY
- [ ] BETTER_AUTH_URL 是正式主域名（https://www.你的域名）
- [ ] ANTHROPIC_API_KEY 只出现在服务端文件：grep -rn "ANTHROPIC_API_KEY" app components lib
- [ ] Anthropic 控制台已设置每月用量上限
## C. 数据库
- [ ] 正式库已应用全部迁移（按 DAY 54 的方式确认）
- [ ] 测试数据已清理：没有“【测试】”“【演练】”开头的提问，没有测试用的 look
- [ ] 今天做过一次 pg_dump 备份，并用 pg_restore --list 验证
- [ ] 故障手册写明了历史窗口和恢复步骤
## D. 功能冒烟（在正式域名上操作）
- [ ] 首页打开正常，照片清晰
- [ ] 三个世界页都能打开，内容和世界对应
- [ ] 链接页四个按钮分别打开小红书、TikTok、Facebook、Instagram 的真实主页
- [ ] 测试小游戏做三遍，分别得到绅士、街头、泰风；“分享我的结果”跳转正确
- [ ] 提问箱提交一条 → 后台看到待审核 → 通过并回答 → 前台显示
- [ ] 后台登录 → 进入 /admin → 退出；退出后访问 /admin 被带到登录页
- [ ] 新建一条带照片的 look → 前台显示 → 删除
- [ ] 文案助手生成一次草稿
- [ ] 看板有数据，图表正常
## E. 内容
- [ ] 没有错别字，没有“占位”“TODO”“example.com”字样
- [ ] 所有文案守住“说事情不说情话”
- [ ] 图片都有有意义的 alt 文字
- [ ] 提问箱旁写明：提问审核后会公开显示，请不要填写手机号等个人信息
## F. 性能与体验
- [ ] 首页手机模式 Lighthouse 性能分 >= 90（正式域名，3 次取中间值）
- [ ] 最窄的手机屏幕上没有横向滚动，按钮都好点
- [ ] 404 页和错误页在手机上显示正常
## G. 分享与 SEO
- [ ] 每个页面标题不同；三个测试结果的分享卡片正确
- [ ] /sitemap.xml 和 /robots.txt 使用正式域名
- [ ] 浏览器标签页显示的是你自己的网站图标，不是框架自带的默认图标
## H. 安全
- [ ] 提问箱限流生效（10 分钟内第 4 条被拒绝）
- [ ] 后台所有 Server Action 和 Route Handler 都检查登录（DAY 70 已审查）
- [ ] 错误页只显示错误编号，不显示报错细节
## I. 域名与 HTTPS
- [ ] http 跳转到 https，非主域名跳转到主域名：curl -I 验证
- [ ] 域名已开启自动续费，到期日写进故障手册
## J. 运维
- [ ] 知道 Logs 在哪，记得 Hobby 版日志只保留 1 小时
- [ ] 知道 Instant Rollback 在哪、怎么撤销回退
- [ ] 故障手册已提交到仓库为什么分成这 10 组、每组防的是什么？逐组说明：
npm audit 会检查依赖有没有已知的安全漏洞，它经常报出一堆条目，别慌：重点看 high 和 critical 级别，再看漏洞是否影响你实际用到的功能，看不懂就请 Claude 解释。不要直接运行 npm audit fix --force，它可能把依赖升级到不兼容的大版本，发布日最忌讳这个。git ls-files 列出所有被 Git 跟踪的文件，用它确认 .env 从来没有被提交过；环境变量要在 Vercel 后台亲眼核对，而不是“记得设过”。example.com 的平台按钮，就会让人觉得网站不认真。最后一条是隐私提醒：提问审核后会公开，粉丝有权事先知道，这也能减少她们误填个人信息。create-next-app 建的项目自带一个 app/favicon.ico，是框架的默认图标，换成你自己的；按 Next.js 的文件约定，把一张方形图片放成 app/icon.png 也可以。“冒烟测试”这个词来自电子行业：新电路板第一次通电，先看有没有冒烟，冒烟了就不用往下测了。软件里指的是用最短的时间把最重要的功能都走一遍，确认“基本能用”。清单 D 组就是你的冒烟测试。
同一个网站在不同设备、不同浏览器里可能表现不同。尤其要注意一类很多人会漏掉的浏览器：App 内置浏览器。粉丝在小红书、TikTok、Instagram、Facebook 里点你简介的链接，通常不会跳到 Safari 或 Chrome，而是在 App 自己内置的浏览器里打开。这些内置浏览器的缓存、Cookie、弹窗行为可能和普通浏览器不一样，而这恰恰是你大部分粉丝第一次看到网站的地方。所以测试矩阵要包括它们：
| 设备 / 浏览器 | 为什么要测 |
|---|---|
| iPhone 的 Safari | 粉丝里 iPhone 用户多，Safari 对一些新特性的支持和 Chrome 不同 |
| 安卓手机的 Chrome | 屏幕尺寸和字体渲染差别大，可以借朋友的手机 |
| 电脑的 Chrome 和 Safari | 你自己用后台的环境；部分粉丝用电脑 |
| 四个 App 的内置浏览器 | 粉丝从简介点进来的真实环境 |
另外，如果条件允许，请一位在中国大陆的朋友再用手机打开一次，DAY 69 学过，Vercel 无法保证大陆的访问体验，发布前心里要有数。
测试中发现问题时，记录要写得让“明天的你”或 Claude 能直接照着重现。一条好的问题记录包含五样东西：在什么设备和浏览器上（比如“iPhone，Instagram 内置浏览器”）；操作步骤（“打开链接页，点小红书按钮”）；预期看到什么（“打开我的小红书主页”）；实际看到什么（“页面空白”）；截图或录屏。只写“链接页有问题”，过两个小时你自己都想不起是哪个手机、点了哪里。
还要分清“发布阻塞”和“可以之后修”。会让粉丝用不了主要功能的（测试做不完、提问提交不了、某个 App 里完全打不开），是阻塞问题，修好再发布；只是某台手机上间距有点挤、某个图标稍微模糊的，记进 issue，发布后处理。这和 DAY 70 的分级是同一个思路。
正式发布时给代码打一个“版本标签”，就像给这一天拍一张定格照：以后无论代码怎么改，你都能准确找回“v1.0.0 正式版那天的代码是什么样”。版本号通常遵循“语义化版本”规则，格式是“主版本.次版本.修订号”：修一个 bug，修订号加一（1.0.1）；加一个新功能，次版本加一（1.1.0）；做了不兼容的大改，主版本加一（2.0.0）。今天是第一个正式版，就是 v1.0.0。
git switch main
git pull
git tag -a v1.0.0 -m "三岁的东哥 正式版 v1.0.0"
git push origin v1.0.0逐行解释：先确保在最新的 main 上；git tag -a 创建一个“附注标签”，-a 表示带说明信息，-m 后面是说明；标签默认不会随 git push 推送，要单独 git push origin v1.0.0。
然后在 GitHub 上发布一个 Release（版本发布页），写上这个版本有什么。先写好说明文件：
dongge-web/docs/release-v1.0.0.md
# 三岁的东哥 v1.0.0 正式版
## 功能
- 三个世界：绅士、街头、泰风
- 链接页：小红书、TikTok、Facebook、Instagram
- 测试小游戏，三种结果各有专属分享卡片
- 粉丝提问箱，审核后显示
- 内容工作台：looks 管理、提问审核、AI 文案助手、数据看板
## 安全与稳定
- 提问箱和文案助手限流，蜜罐识别机器人
- 自定义 404 和错误页，错误编号可在日志中追踪
- 做过备份恢复演练，有故障手册
- 使用自己的域名，全站 HTTPS
## 已知问题
- 从中国大陆访问的速度和可用性无法保证gh release create v1.0.0 --title "v1.0.0 正式版" --notes-file docs/release-v1.0.0.md --verify-taggh release create 在 GitHub 上创建一个版本发布；--title 是标题；--notes-file 从文件读取说明；--verify-tag 要求这个标签已经推送到 GitHub，没有就停下来，防止它自动用别的提交创建标签。完成后仓库首页右侧会出现 Releases，点进去就能看到。
标签和发布说明看起来像“仪式”，其实很实用。以后线上出了问题，你可以用 git diff v1.0.0 main 一眼看出“从正式版到现在改了哪些东西”，问题多半就藏在这些改动里；想看某个功能是哪个版本加的，翻一翻 Releases 就知道。发布说明也是写给未来的你看的项目日记。
四个平台的简介里通常只能放一个链接，而且各平台对简介链接的规则不同（有的对账号有条件要求，有的只显示文字、不能点击），规则还会变化，以各平台当前的规则为准。几条通用建议：
/links 页。选定一个，四个平台保持一致。发一条上线的内容也很自然，文案同样守住“说事情不说情话”。比如：“做了 72 天的网站今天上线了。三个世界的照片、一个 6 道题的小测试，还有一个提问箱，问题我会挑着认真回答。链接在简介。”说清楚网站上有什么、去哪里找，不需要煽情。
发布不是终点。第一周是问题最容易暴露的时候：真实的粉丝会用你没想到的方式使用网站。建议的节奏：
一周后回头看 DAY 64 需求文档里写的“成功的样子”：有多少位访客做完了测试？提问箱收到了多少提问？哪个平台带来的点击最多？用看板上的真实数字判断正式版有没有达到目标，而不是凭感觉。数字不理想也没关系，它正好告诉你下一步该在哪里用力。明天是最后一天：写复盘，找出薄弱点，决定下一步往哪走。
宣布冻结，同步代码
cd ~/code/dongge-web
git switch main
git pull
git status在本子上写一句：“今天只修清单检查出的小问题，不加新功能。”
建立你的上线清单
新建分支 docs/launch，把上午的清单复制成 docs/launch-checklist.md，按你项目的实际路径和功能增删条目。
让 Claude 找漏项
把“问 Claude”第 1 条提示词发给它。它补充的条目，你判断有道理就加进清单。
A、B 组：自动检查
gh issue list --label P0
gh issue list --label P1
gh run list --branch main --limit 1
npm run lint
npx tsc --noEmit
npm test
npx playwright test
npm run build
grep -rn "console.log" app components lib
npm audit
git ls-files | grep -i env
grep -rn "ANTHROPIC_API_KEY" app components lib
grep -rn "example.com" app components lib逐条对照清单打勾。console.log 如果是调试遗留就删掉；npm audit 的结果看不懂就贴给 Claude 解释。再到 Vercel 项目的 Environment Variables 页面，核对生产环境 5 个变量都在；到 Anthropic 控制台确认用量上限。
C 组：清理测试数据，做发布前备份
在 Neon 的 SQL 编辑器里选正式分支，先查再处理：
SELECT id, content, status FROM "Question" WHERE content LIKE '【测试】%' OR content LIKE '【演练】%';确认查出来的都是测试数据后，在后台把它们设为隐藏，或者用 DELETE 删除（WHERE 条件和上面完全一样）。再检查 looks 列表里有没有测试用的条目，在后台删除或取消发布。最后按 DAY 68 的命令做一次 pg_dump，并用 pg_restore --list 验证。
D、E 组：电脑上的冒烟测试
在电脑的 Chrome 里用正式域名，按 D 组逐项操作，一边操作一边看内容有没有错别字和占位文字。然后在 Safari 里再走一遍首页、测试和提问箱。新建记录文件：
dongge-web/docs/launch-log.md
# 发布记录 v1.0.0
| 设备 / 浏览器 | 首页 | 世界页 | 链接页 | 测试+分享 | 提问箱 | 备注 |
| Mac Chrome | | | | | | |
| Mac Safari | | | | | | |
| iPhone Safari | | | | | | |
| 安卓 Chrome | | | | | | |
| 小红书内打开 | | | | | | |
| TikTok 内打开 | | | | | | |
| Instagram 内打开 | | | | | | |
| Facebook 内打开 | | | | | | |发现的错别字、错链接、缺少的隐私提醒、默认图标这类小问题，集中在 docs/launch 分支上修，走 PR 合并。
手机浏览器测试
在 iPhone 的 Safari 和一台安卓手机的 Chrome 上，按记录表的五列各走一遍，填上结果。重点看：照片是否清晰、按钮是否好点、测试做完能否跳到分享页、提问能否提交。
F 到 J 组：剩下的检查
用无痕窗口对正式域名首页跑 3 次 Lighthouse；用 curl -I 验证 https 和主域名跳转；在提问箱连续提交 4 条“【测试】限流”确认限流生效，然后到后台隐藏它们；打开 /sitemap.xml 和 /robots.txt 看域名；确认你知道 Logs 和 Instant Rollback 的位置。
打标签，发布 Release
先把 docs/launch 分支（清单、记录、小修改）合并进 main。写好 docs/release-v1.0.0.md（可以用“问 Claude”第 2 条提示词起草，你来改），提交合并后：
git switch main
git pull
git tag -a v1.0.0 -m "三岁的东哥 正式版 v1.0.0"
git push origin v1.0.0
gh release create v1.0.0 --title "v1.0.0 正式版" --notes-file docs/release-v1.0.0.md --verify-tag更新四个平台的简介
在小红书、TikTok、Facebook、Instagram 的资料编辑页，把简介里的链接换成你的正式网址（四个平台一致）。改完后，在每个 App 里打开自己的主页，点一下链接，按记录表把“App 内打开”四行填完。
发一条上线内容，盯一小时日志
如果你决定发上线内容，可以用“问 Claude”第 3 条提示词起草几版文案，你来挑来改。发出后打开 Vercel Logs 的 Live 模式，看一小时内有没有 5xx 错误；同时在后台看有没有新提问进来。把观察结果写进 docs/launch-log.md。
完成验收
检查 docs/launch-log.md 的设备表：每一格都有结果，有问题的写在备注里并已经处理或建了 issue。提交这份记录。明天写复盘，并决定下一步的方向。
git tag -d v1.0.0 删本地标签、git push origin --delete v1.0.0 删远程标签，再在正确的提交上重打。已经创建了 Release，先用 gh release delete v1.0.0 删掉发布页（会要求确认），再处理标签。npm audit fix --force 可能把依赖升到不兼容的大版本，发布日不要用。把结果贴给 Claude，先弄清是否真的影响你，需要升级的建 issue，发布后单独处理。在手机、电脑、不同浏览器上各打开一遍，功能都正常。请展示你的记录，并说明你是怎么测的。
展示 docs/launch-log.md 的设备表：Mac 的 Chrome 和 Safari、iPhone 的 Safari、安卓的 Chrome，以及小红书、TikTok、Instagram、Facebook 四个 App 的内置浏览器，每一行的首页、世界页、链接页、测试加分享、提问箱都有结果。测法是按清单 D 组在正式域名上真实操作：测试做到出结果并点“分享我的结果”，提问真的提交并在后台看到。有问题的格子在备注里写了现象和处理方式。
发布后第二天，有粉丝说提问箱提交时报错，你按什么顺序处理？
先记录：问清时间、手机和浏览器（是不是在某个 App 里打开的）、页面上的提示或错误编号。自己用同样的环境重现一遍，同时打开 Vercel Logs 的 Live 模式看这次请求的报错（Hobby 版日志只有 1 小时，所以要重现）。如果是最近一次部署引起的、影响所有人，先用 Instant Rollback 回退止血。然后建 issue，在新分支上先写能重现问题的测试，再修复，走 PR 合并，验证后撤销回退，打 v1.0.1 标签，在故障手册里记一笔。最后回复这位粉丝问题已经解决。
为什么发布日不加新功能？
每一行新代码都可能带来新问题，而发布日没有时间给新功能做完整的测试和审查。清单是针对已经审查过、测试过的代码设计的，加了新功能，前面的检查就部分失效了。发布日人又兴奋又着急，最容易出错。所以只修清单检查出来的小问题，新想法记进 issue，等网站稳定运行后再按正常流程做。
昨天网站正式上线，四个平台的简介里都放上了你自己的网址。72 天前，你还不知道终端里的 cd 是什么意思；今天你有一个带数据库、登录、后台、AI 助手、测试、CI 和自己域名的全栈网站。在开始下一段之前，停下来认真回头看一次，这就是复盘。
复盘不是写感想，也不是后悔“当初要是……就好了”。复盘要回答三个问题：发生了什么（事实）、为什么会这样（原因）、下次怎么做（行动）。它最大的价值在于把“模模糊糊的感觉”变成“清清楚楚的结论”。比如“我觉得 React 挺难的”是感觉；“DAY 31 状态提升那天我卡了 3 小时，因为没搞清楚 state 应该放在哪个组件，最后画了组件树才想通；现在遇到新组件我会先画树”是结论，下次能直接用。
这次复盘还有一个特别重要的部分：诚实地区分“我会的”和“我看 Claude 做过的”。后半程你是指挥，大量代码由 Claude 实现。读懂和会写是两回事，就像看过别人开车和自己会开车是两回事。这不丢人，这正是 L4 协作的分工；但你要清楚边界在哪，下一步才知道往哪里补。
复盘从数据开始，不从感觉开始。几条命令能帮你拿到事实：
cd ~/code/dongge-web
git log --oneline | wc -l
gh pr list --state merged --limit 500 --json number --jq length
git log --grep="Co-Authored-By: Claude" --oneline | wc -l
npx vitest run
npx playwright test --list逐行解释：第二行统计 dongge-web 一共有多少次提交（wc -l 数行数）；第三行统计合并了多少个 PR，--json number --jq length 表示取出 PR 列表再数一共几个；第四行统计提交信息里带 Claude 署名的提交，Claude Code 帮你提交时通常会在提交信息末尾加一行 Co-Authored-By，这个数字能粗略反映有多少提交是它参与完成的（如果你的提交习惯不同，这个数字只作参考）；最后两行分别显示 Vitest 测试通过的数量和 Playwright 测试的总数。再打开后台看板，记下上线后的访客和提问数据。
dongge-web/docs/retro.md
# 72 天复盘
## 1. 基本数据
- 学习天数：72 天
- dongge-web 提交次数：
- 合并的 PR：
- 带 Claude 署名的提交：
- 测试数量：Vitest __ 个，Playwright __ 个
- 上线一周：做完测试 __ 次，收到提问 __ 条，点击最多的平台 __
## 2. 学会了什么（每个阶段一句话，写“我能做到什么”）
- 阶段 0 起步：
- 阶段 1 HTML + CSS：
- 阶段 2 JavaScript：
- 阶段 3 TypeScript + React：
- 阶段 4 Next.js 全栈：
- 阶段 5 AI 与数据：
- 阶段 6 打磨上线：
## 3. 最难的三件事
| 事情 | 难在哪里 | 最后怎么过去的 | 现在还怕不怕 |
## 4. 哪些是 Claude 替我做的
| 功能 / 文件 | 谁写的（我 / 结对 / Claude） | 不借助 AI 我能重写吗 | 不能的话缺什么 |
## 5. 做得好的习惯（继续保持）
## 6. 要改的习惯
## 7. 最薄弱的 3 个知识点
| 知识点 | 证据 | 两周练习计划 | 验收方式 |
## 8. 下一步
- 方向：
- 为什么选它：
- 第一周计划：写的时候注意三点。“学会了什么”要写成能力，比如“我能从零建一个 Next.js 项目并连上 Neon 数据库”，而不是“学了 Next.js”。“最难的三件事”里，“最后怎么过去的”最有价值，它就是你的学习方法。“哪些是 Claude 替我做的”要逐个功能填，“不借助 AI 我能重写吗”这一列请诚实，它直接决定第 7 部分。
检验一个人懂不懂全栈，最好的办法是让他讲清一个请求从头到尾经过了哪些层。今天的验收题就是这个。先看第一条路线：粉丝在手机上提交一条提问。
| 层 | 这一层做了什么 | 项目里对应的东西 | 坏了去哪查 |
|---|---|---|---|
| 浏览器 | 显示表单，粉丝输入内容点提交；客户端组件负责交互 | components/AskForm.tsx | 开发者工具的 Console |
| DNS | 把 www.你的域名 解析成 Vercel 的地址 | 注册商里的 A 和 CNAME 记录 | dig |
| HTTPS 与 Vercel | 建立加密连接，证书证明身份，把请求交给你的服务端代码 | Vercel 的域名设置和部署 | Vercel 的 Domains 和 Deployments |
| Next.js 服务端 | Server Action 执行：蜜罐、Zod 校验、限流 | app/ask/actions.ts、lib/rate-limit.ts | Vercel Logs |
| ORM | Prisma 把 prisma.question.create 翻译成 SQL | lib/prisma.ts、schema.prisma | 日志里的 Prisma 报错 |
| 数据库 | Neon 执行 INSERT，存进 Question 表，状态 PENDING | Neon 新加坡区域 | Neon 的 SQL 编辑器 |
| 后台 | 你登录（Better Auth 用 Cookie 保存会话），审核通过，revalidatePath 让前台页面更新 | app/admin/questions、lib/auth.ts | Vercel Logs |
| 回到前台 | 下一位访客打开提问箱，服务端组件查出已通过的提问，渲染成 HTML | app/ask/page.tsx | 页面本身 |
第二条路线：粉丝把测试结果发给朋友。聊天软件的机器人访问 /quiz/result/street；这个页面构建时就生成好了，generateMetadata 生成的 og 标签里有标题、描述和分享图地址；机器人再去取 opengraph-image，它是用 ImageResponse 把 JSX 画成的 PNG；聊天框里出现卡片；朋友点开，看到结果和“我也测一测”，进入 /quiz，一个新访客就这样来了。能把这两条路线讲清楚，而且每一层都能说出“坏了去哪查”，你就真正理解了自己的网站。
自己找自己的薄弱点很难，因为不知道自己不知道什么。今天换个用法：让 Claude 当考官。它读你的代码、复盘和提交历史，一次问你一个问题，你答完它再评分讲解。这样暴露出来的问题，比你自己想的准确。关键的要求是“一次一题、先答后讲”，否则它会一口气把答案都说出来，你就只是在“看”，没有在“想”。
找到薄弱点之后，练习方法有一条原则：在这个知识点上，把协作级别调回低处。DAY 01 到 24 是 L1（Claude 只讲解和出题，代码你自己敲），对薄弱的知识点就回到 L1：让 Claude 出题、只给提示，你自己写。几个例子：
lib/og-font.ts 里的 loadGoogleFont，再给自己讲一遍每个 await 在等什么。每个练习都要有验收方式，比如“不看资料，20 分钟内写出来并通过我事先写好的 3 个测试”。没有验收的练习，很容易变成“看了一遍觉得懂了”。
第一个方向是学一门后端语言 Go，用它把点击统计这一小块单独做成一个服务，部署到你自己在新加坡的云服务器（AWS EC2）上。为什么值得？这 72 天里，Vercel 替你做了很多事：准备服务器、运行程序、配 HTTPS、收集日志、出错重启。你知道它们存在，但没有亲手做过。自己管一台服务器，这些“看不见的工作”会变得看得见。你桌面上旧官网文件夹里的 deploy.sh 和 nginx-dongge.conf，就是这类工作的痕迹，到时候你就能读懂它们了。Go 编译出来是一个单独的可执行文件，部署简单、运行快，很适合做这种小服务。
整体设计是这样的：Go 服务只做一件事，接收“某个平台按钮被点了一次”，写进 DAY 60 建的那张点击统计表（同一个 Neon 数据库）；链接页的按钮改成把点击发给 Go 服务的地址，比如 https://api.你的域名/click（DAY 69 学过，子域名用一条 DNS 记录就能开）；后台看板完全不用改，因为它读的还是同一张表。一个 4 周的大致路线：
go test 测试。api 子域名指向它。浏览器从 www 域名向 api 域名发请求，还要学跨域（CORS）的配置。第二个方向是手机 App。可以分两步走。第一步成本很低：把网站做成 PWA（渐进式网页应用），Next.js 有官方指南，加一个 manifest 文件后，粉丝可以把网站“添加到主屏幕”，看起来像一个 App。第二步才是真正的原生 App：用 React Native 加 Expo，你学过的 React 和 TypeScript 大部分能用上；但要为 App 专门准备数据接口、处理手机上的登录，发布到应用商店还要注册开发者账号（通常要付费）并通过审核，以官方规则为准。老实说，对个人 IP 官网来说，粉丝未必需要一个 App，这个方向的主要价值是学习。
第三个方向是继续给网站加功能。好处是马上对你的 IP 有帮助，而且在熟悉的技术栈里，能继续练“当指挥”。候选可以从 DAY 64 需求文档的“明确不做”和上线后的数据里找：比如 TikTok 和 Instagram 上有海外观众，做一个英文版；给简介链接加上来源参数，看出哪个平台来的粉丝最爱做测试；改进文案助手的提示词。规则不变：每个新功能都从一份需求和验收标准开始。
| 方向 | 主要学到什么 | 对 IP 的直接帮助 | 成本 |
|---|---|---|---|
| Go 进阶 + EC2 | 一门新语言、服务器、Linux、nginx、HTTPS、运维 | 小，粉丝感觉不到 | 学习曲线陡；服务器按月付费 |
| 手机 App | 移动端开发、接口设计、应用发布 | 中，取决于粉丝是否需要 | 开发者账号费用；审核和维护 |
| 继续加功能 | 在熟悉的技术栈里做得更深，产品判断 | 大，直接服务粉丝和内容 | 主要是时间；AI 功能有 API 费用 |
没有标准答案。如果你想真正理解“后端”和“服务器”，选 Go；如果你的精力主要在做内容，选继续加功能。重要的是只选一个，至少坚持 4 周，不要三个同时开头、三个都半途而废。
网站就像一辆车，买回来之后还要定期保养。把下面的节奏写进故障手册，并在手机日历里设好提醒：
npm outdated 看哪些依赖有更新，一次升级一个，走分支加 PR，让 CI 帮你把关；看一眼 Vercel、Neon、Anthropic 的用量。72 天走下来，你最大的收获可能不是某个具体的技术，而是一套做事的方法：先想清楚要什么，写成能检验的标准；把大任务拆小；每一步都验证；出了问题先看事实再下结论。这套方法换成 Go、换成 App、换成任何新东西都用得上。下午把复盘写完，把下一步定下来。
收集事实
运行上午的五条命令，打开后台看板记下上线后的数据，全部填进 docs/retro.md 的第 1 部分。
亲手写复盘的第 2 到 6 部分
留出 60 到 90 分钟，自己写，不让 Claude 代写。可以翻看每天的笔记、GitHub 上的 PR 和 issue 帮助回忆。第 4 部分逐个功能填表：提问箱、限流、分享图、后台登录、文案助手、看板……每一行都诚实回答“不借助 AI 我能重写吗”。
在纸上画出分层图
不看课件和代码，在一张纸上画出“粉丝提交提问”经过的每一层，每层旁边写一句它做了什么、坏了去哪查。再画“朋友收到测试结果链接”的路线。画完对照上午的表格，用另一种颜色的笔补上漏掉的。
讲一遍，录下来
用手机录音，对着分层图讲 5 分钟，假装在给一位不懂技术的朋友解释。回放一遍，把讲不清楚、卡住的地方记下来，这些就是薄弱点的候选。
让 Claude 当考官
在 Claude Code 里打开 dongge-web，发送“问 Claude”第 1 条提示词。认真答完 10 题，每题都先自己想，想不出来就直接说“不知道”，不要去翻代码。
定下薄弱点练习计划
把考官总结和你录音时发现的卡点对照，确定 3 个最薄弱的知识点，填进复盘第 7 部分。对每一个，用“问 Claude”第 3 条提示词让它切回 L1 老师模式出练习题；在表格里写好两周练习计划和验收方式。
了解三个方向，各花 30 分钟
Go 方向：打开 A Tour of Go，做完前几节。App 方向：读 Next.js 的 PWA 指南开头部分，看看 Expo 文档首页。继续加功能方向：翻一遍你的 issue 列表（P2 和“以后再说”的那些）和看板数据，挑出最想做的两个功能。
做决定
对照上午的比较表，结合复盘里的薄弱点和你接下来一个月的时间，选一个方向，填进复盘第 8 部分，写清“为什么选它”。
让 Claude 出 4 周计划，你来审
切到 Plan 模式，发送“问 Claude”第 2 条提示词。像 DAY 64 审方案一样审它：每周的产出能不能验收？有没有超出你时间的安排？花钱的地方是不是都提前设了上限？改到满意后，保存为 docs/next-steps.md。
整理仓库
git switch main
git pull
git branch --merged main第三条列出已经合并进 main 的本地分支。除了 main 本身，逐个用 git branch -d 分支名 删掉（-d 只删已合并的分支，比较安全）。再用 gh issue list 看一遍打开的 issue，已经过时的关掉，P2 和以后要做的留着。
写进维护节奏
在 docs/runbook.md 末尾加一节“定期维护”，写上每周、每月、每年要做的事。在手机日历里设三个重复提醒：每周备份、每月查依赖和用量、域名到期前一个月。
提交复盘，完成最后的验收
git switch -c docs/retro
git add docs/retro.md docs/next-steps.md docs/runbook.md
git commit -m "docs: 72 天复盘、下一步计划和维护节奏"
git push -u origin docs/retro
gh pr create --fill自己读一遍 PR，合并。最后找一位朋友（或者对着录音），不看代码，把网站每一层怎么工作讲一遍。讲完了，这 72 天就真正结束了。
docs/retro.md 八个部分都写完并合并进 main；你能不看代码讲清网站的每一层。不看代码，给朋友讲清你的网站每一层是怎么工作的。
以“粉丝提交一条提问”为例：她在手机上打开网址，DNS 把我的域名解析到 Vercel；浏览器和 Vercel 建立 HTTPS 加密连接，证书证明这确实是我的网站；页面是 Next.js 在服务器上渲染好的 HTML，提问表单是一个客户端组件。她点提交，数据发给服务器上的 Server Action，它先检查隐藏的蜜罐字段，再用 Zod 校验长度，再按 IP 限流；通过后，Prisma 把保存操作翻译成 SQL，在新加坡的 Neon 数据库里插入一条待审核的记录。我登录后台时，Better Auth 用 Cookie 记住我的登录状态，每个后台操作都在服务端检查登录；我审核通过后，revalidatePath 让提问箱页面更新，下一位访客就能看到。出错时访客看到错误页和编号，我拿编号去 Vercel Logs 找原因；数据出问题时用 Neon 的分支或 pg_dump 恢复。能讲出每一层“做什么”和“坏了去哪查”，就算过关。
你最薄弱的 3 个知识点是什么？各自的练习计划和验收方式是什么？
答案来自你的考官结果和录音。格式示例：知识点“异步和 Promise”，证据是考官第 4 题没答出 await 在等什么、录音里讲分享图字体加载时卡住；计划是两周内每天 30 分钟，先读现代 JavaScript 教程的 Promise 章节，再不借助 AI 重写 loadGoogleFont 和一个带 try/catch 的 fetch 函数；验收方式是不看资料 20 分钟内写出来，并能给别人讲清每一行。三个知识点都要有这样具体的证据、计划和验收。
如果选 Go 进阶，为什么让 Go 服务写入同一张点击表，而不是新建一个数据库？
因为后台看板读的就是这张表，Go 服务写进同一张表，看板一行代码都不用改，新旧系统可以平滑切换：先让一部分点击走 Go 服务，确认数据正常再全部切过去，出了问题随时切回 Next.js 的接口。新建数据库就要同时改看板、迁移历史数据，两边的数据还可能对不上。一次只改一处，是降低风险的基本原则。