FAQ

FAQ

常见问题速查。更深的运维备忘见仓库 docs/knowledge/firefly-ops.md（勿与本页双写长文）。

安装 / 工具链

Q: 为什么不能用 npm / yarn？
A: preinstall 强制 pnpm。请用 pnpm 9。

Q: pnpm install 报 404？
A: 镜像源问题。加 --registry https://registry.npmjs.org。

Q: Node 版本？
A: ≥ 22。低于 22 构建容易挂。

本地预览

Q: 4321 连不上？
A: 先确认仓库根已跑 pnpm dev。Cursor/终端会话结束后后台进程不会自动复活。

Q: 8090 和 4321 有什么区别？
A: 4321 = 博客站点；8090 = README/Release 的本地 HTML 预览壳。见 Getting-Started。

Q: 开发时搜索不好用？
A: Pagefind 索引在 pnpm build 之后生成；dev 下能力有限，属预期。

配置与内容

Q: 改站先改哪里？
A: src/config/。见 Configuration-Overview。

Q: 官方文档里评论是 none，本站呢？
A: 官方默认 ≠ 本站。本站评论是 Waline（commentConfig.type: "waline"）。决策见 docs/adr/0001-waline-over-giscus.md。

Q: 音乐是不是必须接 Meting？
A: 默认 本地曲库（musicConfig.mode = local）。见 docs/adr/0002-local-music-default.md。

Q: 草稿箱和 draft: true 有什么区别？
A: 草稿箱 = src/content/posts/_draftbox/，gitignore、不 push；本地 pnpm dev 可预览。主题示例里带 draft: true 且入库的 demo 帖是另一回事。见 Writing-Posts。

Q: 正文里半角冒号怪事？
A: 站点引擎可能把半角 : 后内容当成 HTML 标签解析。正文说明性冒号优先用全角 ：。

部署

Q: 默认部署到哪？
A: Vercel 项目 fork-firefly。见 Deploy-Vercel。

Q: 要不要开 Cloudflare Workers？
A: 本仓默认静态站。勿随意设 CF_WORKERS，除非你明确要切 adapter。

Q: 换域名要注意什么？
A: 同步改 siteConfig.site_url（影响 site、OG、sitemap 等）。