---
name: chatu-verify
description: 改完代码后的运行时自检——真的把页面请求一遍，确认没有白屏/500/报错，而不是只靠 tsc 通过就宣称完成。每轮交付前使用；也用于"用户说打不开但你觉得没问题"时取证。
---

# 运行时自检：别只信编译器

`npx tsc --noEmit` 通过**不等于**页面能打开——Server Component 里抛异常、平台能力用错、数据为空导致的渲染崩溃，全都只在真正请求页面时才暴露。**每轮改完、在向用户汇报"做好了"之前，按下面三步走一遍。**

## 三步自检

### 1. 请求页面，看状态码

dev server 就在本机 **3001** 端口：

```bash
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/
```

- `200` → 继续第 2 步
- `500` → 服务端渲染抛错，直接去第 3 步看日志堆栈
- 连不上 / 长时间无响应 → dev server 没起来或正在编译，等几秒重试；仍不行看第 3 步日志

**改了哪些页面就把哪些路由都请求一遍**（新增的 `/todos`、`/login`、详情页 `/items/1` 等），不要只测首页。

### 2. 看返回的内容对不对

```bash
curl -s http://localhost:3001/ | head -c 3000
```

判断要点：
- 出现了你写的业务文案/字段名 → 基本正常；
- HTML 里几乎没有内容、只有空壳 `<div id="__next">` 或骨架 → **白屏**，多半是数据层抛错被吞或渲染逻辑短路；
- 出现 `Application error`、`Unhandled Runtime Error`、Next 错误浮层相关标记 → 有运行时错误，去第 3 步。

### 3. 看 dev server 日志

日志文件是**整个会话累积**的，直接 `tail` 很可能全是上一轮的内容。runtime 会在每轮开始时写一行
`---- round <xid> start ----`，用它只取本轮：

```bash
tail -n 2000 /app/logs/builder-devserver.log \
  | awk '/---- round .* start ----/{buf=""} {buf=buf $0 ORS} END{printf "%s", buf}' \
  | tail -n 200
```

前后两个 `tail` 都不能省：前面限制读入量，后面给输出封顶——本轮如果是第一轮、或沙箱还在跑旧 runtime
（日志里没有标记），中间那段 `awk` 会把读到的全部内容原样吐出来。

编译错误、Server Action 抛错、平台 API 报错（`KV_*` / `DB_*` / `AUTH_*` / `AI_*`）都在这里。按 `chatu-debug` 的对照表修。

看到 `[runtime] --- 日志已轮转 ---` 说明更早的内容被挪到了 `builder-devserver.log.1` / `.2`，需要时去那里翻。

## 可选：看一眼实际渲染效果

需要确认布局/样式（用户说"丑""错位""图没出来"）时，可以用 Playwright MCP 打开 `http://localhost:3001/` 截图查看。注意：首次启动该工具较慢，**只在视觉问题上用**，功能自检用上面的 curl 三步就够了。

## 通过标准与如实汇报

一轮交付前，至少满足：

- [ ] `npx tsc --noEmit` 无错误
- [ ] 本轮涉及的每个路由都返回 200
- [ ] 页面内容里能看到预期的业务文案，不是空壳
- [ ] dev server 日志里没有本轮新增的报错

**没做到就不要说"已完成"。** 修不动时（`chatu-debug` 的 3 次迭代上限用尽），如实告诉用户：哪个页面、什么错、你试过什么、建议怎么办——不要含糊地说"应该可以了"。

## 禁忌

- 不要因为"代码看起来没问题"就跳过自检；白屏几乎都是这么漏出去的。
- 不要自行重启 dev server 来"刷新一下"（重启不解决代码错误，见 `chatu-debug`）。
- 不要 curl 外网地址来"验证应用"——自检只针对本机 3001。
- 不要把自检命令写进项目代码或 package.json scripts，它只是你的检查动作。