偏「打开项目就能干活」的清单。本站本身是 Astro + Starlight；也经常碰 Next / React。
| 想做什么 |
命令 |
| 固定 Node 版本（mise） |
mise use node@22 |
| 装依赖 |
pnpm install（优先）/ npm i |
| 加依赖 |
pnpm add 包 / pnpm add -D 包 |
| 跑脚本 |
pnpm dev / pnpm build / pnpm preview |
| 一次性 CLI |
pnpm dlx create-xxx / npx |
| 看为何装了某个包 |
pnpm why 包名 |
| 想做什么 |
命令 |
| 开发 |
astro dev 或 astro dev --background |
| 构建 |
astro build |
| 预览 |
astro preview |
| 类型 / 内容 |
构建时会 sync content；改 astro.config.mjs 会清 content store |
内容放 src/content/docs/**，侧栏在 astro.config.mjs 的 sidebar。静态部署到 Cloudflare Workers 时注意 prerenderEnvironment: 'node'（satteri 相关）。
| 想做什么 |
命令 |
| 开发（本机回环） |
pnpm dev（PC·XRAY 绑 127.0.0.1） |
| 构建 / 启动 |
pnpm build / pnpm start |
| 类型检查 |
pnpm typecheck |
| 场景 |
做法 |
| 样式不对 |
DevTools → Computed；注意 cascade / @layer（Starlight） |
| 接口 4xx/5xx |
Network 面板看 Request/Response；curl -i 复现 |
| Hydration 报错 |
查服务端/客户端首屏 HTML 是否不一致（Date、random、浏览器 API） |
| 包体积 |
pnpm build 看产物；Next 可用 bundle analyzer |
| 环境变量 |
分清 PUBLIC_ / NEXT_PUBLIC_（会进浏览器）与仅服务端变量 |
- 交互控件要有可见焦点与键盘路径
- 图片给宽高或
aspect-ratio，避免 CLS
- 不要在客户端塞密钥
pnpm build 在推送前至少本地过一遍
