命令行

blume <command> [options]

命令#

通用选项#

• blume init — 在终端里，它会引导你回答几个问题（项目建在哪里、站点名称、模板、内容源）；下面的每个选项都预先回答了其中一个问题。
• blume init --yes — 跳过所有提问，用默认值生成脚手架（在 CI 中或 stdin 不是终端时也是这个行为）。
• blume init --content-dir <dir> — 设置内容目录（默认 docs）。
• blume init --template docs|api|sdk|changelog — 从一个起始模板生成脚手架（用 API 参考、SDK 或更新日志，替代普通的文档种子）。
• blume init --package-manager npm|pnpm|yarn|bun — 用指定的包管理器安装依赖，并打印对应的后续步骤（默认：运行 blume init 的那个）。
• blume init --no-install — 只写文件、跳过依赖安装，适用于 CI 或自定义的依赖流程。默认情况下 blume init 会运行包管理器的安装命令，让项目开箱即可运行；如果安装失败，脚手架会被保留、重试命令会被打印出来，退出码非零。
• blume init --eject — 先生成脚手架，再导出为一个独立的 Astro 项目（配合 --no-install 时，依赖装好后会改为引导你执行 blume eject）。
• blume dev --host --port <n> --open
• blume dev --content-dir <dir> — 扫描另一个内容目录，无需改动 blume.config.ts。
• blume dev --debug — 输出详细的 Astro/Vite 日志，便于排查问题。
• blume dev --preview / blume build --preview — 包含草稿和未发布的 CMS 内容。
• blume build --no-strict — 即使有诊断错误也照常构建。默认情况下 blume build 只要遇到任何错误级诊断就失败（退出码 1），因为 frontmatter 校验未通过的页面会被从产物中丢弃；加上 --no-strict 后构建会成功，并报告有多少页面被丢弃。blume dev --strict 让开发模式采用同样的快速失败行为。
• blume build --analyze — 构建后打印客户端 JavaScript 各包的体积（从大到小）。
• blume build --budget-js <kb> --budget-css <kb> — 当客户端 JavaScript/CSS 总量超出预算时让构建失败，把性能目标变成一道 CI 关卡。
• blume build --isolated — 构建到一个一次性的 .blume-verify/ 运行时（以及它自己的 dist/）中，而不是 .blume/，这样正在运行的 blume dev 服务器和你真正的 dist/ 都不会被影响。参见开发服务器运行时如何校验。
• blume preview --host --port <n> — 绑定预览服务器。
• blume sync --force — 先丢弃缓存快照，再重新拉取远程源。
• blume sync --preview — 包含草稿和未发布的 CMS 内容。
• blume sync --strict — 遇到诊断即失败。
• blume add <item> --force — 覆盖已存在的文件。
• blume check --preview — 检查时包含草稿和未发布的 CMS 内容。
• blume check --strict — 内容诊断与类型错误都导致失败。
• blume check --isolated — 在一次性的 .blume-verify/ 运行时中做类型检查，使正在运行的 blume dev 服务器不受影响。参见开发服务器运行时如何校验。
• blume eject --yes — 跳过确认提示。
• blume eject --force — 在已经导出的应用上再次导出，覆盖其 astro.config.mjs 和 src/。

有独立页面的命令会把自己的全部选项都列在那一页：blume doctor、blume validate、blume audit、blume eval、blume translate 和 blume version。blume validate、blume doctor、blume audit、blume eval 和 blume translate 接受 --json，把机器可读的结果打印到 stdout，供 CI 和编辑器集成使用（诊断的数据结构见 validate）；build、check 和 dev 只向终端输出。每个命令都会拒绝自己不接受的选项，并给出最接近的那一个作为建议、同时列出它真正接受的选项，因此像 --isolatd 这样的拼写错误会直接失败，而不会被悄悄忽略。

开发服务器运行时如何校验#

blume dev 提供的是一个以生成的 .blume/ 运行时为根的实时 Astro 服务器，并在每次改动后重新生成它。blume build 和 blume check 重新生成的是同一个 .blume/，因此在开发服务器运行时执行其中任何一个都会把它弄坏——两者都会报错并以非零码退出：

A `blume dev` server is running at http://localhost:4321; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.

--isolated 就是那个逃生舱。它把整个生成的运行时（对 build 来说还有它输出的 dist/）挪到同级的 .blume-verify/ 目录，因此校验过程绝不会写入开发服务器（或你真正的 dist/）所依赖的任何东西：

# 在第二个终端里，`blume dev` 正在运行时：
blume check --isolated   # 快：只对 .astro/config 的改动做类型检查
blume build --isolated   # 彻底：把生产构建完整渲染到 .blume-verify/dist

check --isolated 是快捷路径（Astro 类型与模板诊断，不产出 dist/）；build --isolated 更重，还会捕捉运行时渲染错误。隔离构建会跳过部署后的步骤（搜索索引、托管服务同步、llms.txt、sitemap/robots、重定向）——一次校验只需要确认站点能编译、能渲染，不需要把它发布出去。--analyze 以及 --budget-js/--budget-css 两道关卡仍然会跑，只是以隔离产物为基准。Blume 会自动把 .blume-verify/ 加进你的 .gitignore。

当你想让开发服务器一直开着、同时又需要编码 agent 校验改动时，这一点尤其有用。要让普通的 blume build/blume check 不加这个选项也能自动隔离——比如在 agent 的 shell 里——把 BLUME_RUNTIME_DIR 设成要使用的运行时目录：

export BLUME_RUNTIME_DIR=.blume-verify

类型检查#

blume check 会对你的项目运行 astro check。它会重新生成 .blume 运行时、同步 Astro 的内容类型，然后报告所有 TypeScript 错误——无论是在你的 blume.config.ts 里、在自定义的 .astro 页面里，还是在这些页面导入的组件中。有错误时它以非零码退出，因此可以直接当作 CI 中的 typecheck 步骤：

{
  "scripts": {
    "typecheck": "blume check"
  }
}

在项目根目录添加一个继承 Astro 配置的 tsconfig.json，这样手写的页面才能解析 blume/* 导入以及 blume:data 这类虚拟模块：

{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", "**/*"]
}

没有项目级 tsconfig.json 时，只会检查生成的运行时。