Troubleshooting

Troubleshooting

短诊断步骤。更长运维备忘：主仓 docs/knowledge/firefly-ops.md。常见问答：FAQ。

端口连不上（4321 / 8090）

1. Get-NetTCPConnection -LocalPort 4321,8090（或 netstat）看是否在听
2. 空 → 仓库根重跑 pnpm dev 或 python -m http.server 8090
3. 别用 file:// 开 preview 壳
4. 会话结束后后台进程不会自动复活 — 属预期

安装失败

• 必须用 pnpm 9
• npmmirror 404 → pnpm install --registry https://registry.npmjs.org
• Node < 22 → 升级

构建 / 搜索

• pnpm build 前半段 LQIP 失败会挡住 Astro
• 搜索只有 build 后 Pagefind 才完整 → Search-Pagefind
• 误开 CF_WORKERS 会切 Cloudflare adapter — 静态站勿乱开

配置「按官方抄了却不对」

先打开 Official-Docs-Map：评论/音乐/主题模式等本站与出厂不同。
真理：src/config/* + docs/adr/。

正文渲染怪异

半角 : 偶发被当 HTML 标签 — 说明性冒号用全角 ：。
见 Writing-Posts / FAQ。

布局改炸

刚动过 Layout.astro / MainGridLayout.astro？这两文件挂 Swup/壁纸/桌宠/音乐钩子 — 回滚或缩小 diff。见 Architecture。

性能复测「改了却没变化」

1. 本地 server 锁 dist：有进程 serve 着 dist/client（如 python -m http.server），pnpm build 产物不更新，复测全是旧包的假象。先 rm -rf dist .astro + 停掉占用进程再 build。
2. .astro 缓存被清：dev server 文章列表空 / 文章页 404。重启 dev server 让其重建内容集合缓存。
3. 探针打的是旧部署：线上 Preview 有缓存/SSO，确认探针目标是最新 build。性能排查方法见 Performance。

Windows 构建偶发

• EPERM ... symlink（@astrojs/vercel 在 astro:build:done 钩子里 symlink 依赖）：Windows 权限问题，静态产物 dist/client 已生成，Vercel 云端无此问题。本地只需静态产物时可忽略；缺 Pagefind 索引就补跑 npx pagefind --site dist/client && npx tsx scripts/sync-pagefind-output.ts。