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。