项目命令
默认模板 package.json 中提供的开发、检查、数据库和部署命令。
本页收录 saavo-default-template/package.json 中的 npm scripts。除特别说明外，命令都应在初始化后的项目根目录执行。源码包会移除模板维护者使用的 commit 命令，该命令不能视为新建项目的默认命令。
本页依据模板源码版本 0.2.14 核对。运行 npm run 可查看自己项目实际支持的命令；旧模板可能存在差异。仅在 scripts 中添加命令名称不会安装对应实现，使用缺失命令前应对照相应模板源码更新。
开发和预览
| 命令 | 用途 |
|---|---|
npm run predev | 生成内容集合和搜索索引；npm 会在 dev 前自动执行 |
npm run dev | 先生成搜索索引，再启动 Vite 开发服务器 |
npm run build | 生成搜索索引，以生产模式构建访问统计脚本和应用 |
npm run build:preview | 生成搜索索引，以 local-preview 模式构建本地预览版本 |
npm run preview | 执行 build:preview，然后在 127.0.0.1:4173 启动 Vite Preview |
npm run build:analytics | 以开发模式单独构建访问统计脚本 |
predev 是 npm run dev 的生命周期脚本，npm 会自动执行，通常不需要手工运行。
代码检查和测试
| 命令 | 用途 |
|---|---|
npm run lint | 生成内容集合并执行 ESLint |
npm run lint:fix | 生成内容集合并执行 ESLint 自动修复 |
npm run typecheck | 生成内容集合并执行 tsc --noEmit |
npm test | 依次执行应用、脚本、OAuth 限流和 Durable Object 基础组件测试 |
npm run test:app | 生成内容集合后执行应用测试 |
npm run test:scripts | 只执行 scripts/ 对应的测试 |
npm run test:oauth-rate-limit | 只执行 OAuth 限流测试 |
npm run test:primitives | 只执行 Durable Object 基础组件测试 |
npm run test:coverage | 生成内容集合后执行应用测试并生成覆盖率报告 |
npm run verify | 依次执行 lint、typecheck、全部测试和生产构建 |
执行 npm run verify 可以完成全部本地检查。构建成功不能代替类型检查和测试。
内容和类型生成
| 命令 | 用途 |
|---|---|
npm run gen:collections | 根据内容目录重新生成文档和博客集合 |
npm run gen:search-index | 生成内容集合和站内搜索索引 |
npm run cf-typegen | 根据 Wrangler 配置和环境变量重新生成 worker-configuration.d.ts |
npm run kv:sync:local | 生成内容集合，并把文档和博客内容同步到本地 MAIN_KV |
npm run kv:sync:remote | 生成内容集合，并把文档和博客内容同步到远程 MAIN_KV |
src/libs/documentation/source/.content-collections/ 存放生成的集合、类型和缓存，已由 Git 忽略，也不会包含在发布源码包中。saavo:init 会重新生成它；修改内容后，也可以运行 npm run gen:collections 重建。
本地初始化和检查
| 命令 | 用途 |
|---|---|
npm run secret:generate | 输出一个新的 256 位标准 Base64 SAAS_SECRET，不会修改环境变量文件 |
npm run saavo:init | 创建或保留 .env，补充缺失的 SAAS_SECRET，再依次执行 cf-typegen、gen:collections、db:migrate:local 和 doctor |
npm run doctor | 检查本地环境变量、配置、Binding、资源名称和数据库目录 |
npm run doctor:remote | 使用 .env.production 检查生产配置、账号和资源 ID，不等同于验证全部远程服务可用 |
数据库
| 命令 | 用途 |
|---|---|
npm run db:migrate:local | 初始化空的本地 D1，并应用尚未执行的本地迁移 |
npm run db:migrate:remote | 初始化空的远程 D1，并应用尚未执行的远程迁移 |
npm run db:reset:local | 删除本地两个 D1 中的表、视图和触发器，再执行初始化脚本和数据库迁移 |
npm run db:reset:remote | 完整输入确认文字后，重置远程两个 D1，再执行初始化脚本和数据库迁移 |
重置命令会清空数据库
db:reset:local 和 db:reset:remote 都会删除已有数据。脚本不提供撤销操作，恢复依赖事先准备并验证过的备份或数据库恢复能力。不能用重置命令更新生产环境的表结构。
修改数据库表结构时，应在 schema/migrations 中新增迁移文件，再执行相应的 db:migrate 命令。不要直接执行 schema/db-init.sql 或 schema/analytics-init.sql。
部署
| 命令 | 用途 |
|---|---|
npm run deploy:init | 首次部署：检查本地项目，确定 Worker 和资源名称，创建远程资源，部署 Worker，初始化 D1，同步内容并执行健康检查 |
npm run deploy:update | 更新已经初始化的项目：检查远程配置，执行完整验证和数据库迁移，部署 Worker，同步内容并执行健康检查 |
npm run domain:set -- https://app.example.com | 检查生产配置，更新 wrangler.jsonc 和 .env.production 中的自定义域名配置，构建、部署并检查首页 |
deploy:init 只用于第一次远程部署。完成首次部署并具备完整远程资源配置后，后续发布使用 deploy:update。仅写入 account_id 不代表初始化完成，首次部署中途失败时，应先检查已创建的资源和配置，再按部署教程处理，不能根据某一个字段直接切换命令。
deploy:update 要求 .env 和 .env.production 中的 SAAS_SECRET 存在且完全一致。远程迁移会在部署新 Worker 之前执行，因此迁移必须兼容当前仍在线的代码。
domain:set 只修改 Worker 自定义域名和 VITE_SITE_URL。GitHub、Google、Stripe 等第三方平台的回调地址，以及 Turnstile 和邮件发送域名，仍需在相应平台单独更新。
domain:set 不执行完整的 verify、数据库迁移或 KV 同步。如果同时发布代码、数据结构或内容变更，应使用 deploy:update。
Stripe Webhook
| 命令 | 用途 |
|---|---|
npm run webhook:stripe:dev | 读取 .env，使用测试模式密钥创建 Webhook 目标，并写回 STRIPE_WEBHOOK_SECRET |
npm run webhook:stripe:prod | 读取 .env.production，使用生产模式密钥创建 Webhook 目标，并写回 STRIPE_WEBHOOK_SECRET |
这两个命令会调用 Stripe 创建远程 Webhook，不是单纯生成本地配置。脚本会询问接收地址、事件 API 版本和订阅事件。开发环境应提供可被 Stripe 访问的 HTTPS 地址，本地回环地址不能作为远程投递目标。生产配置写回后还需要重新部署，开发配置更新后需要重启开发服务器。
每次成功执行都会创建新的 Webhook 目标，不会更新已有目标。再次运行前应检查已有目标，避免重复投递事件。
版本和发布
| 命令 | 用途 |
|---|---|
npm run release:tag | 交互选择版本，为当前提交创建带说明的 v<version> 标签，并只把该标签推送到 origin |
npm run release:archive -- <tree-ish> <output-path> | 把指定 Git Tree 打包为可复现的源码 ZIP |
release:tag 默认使用 package.json 中的版本号，不会修改文件、创建提交或推送当前分支。输入其他版本号时，脚本会给出警告，但仍允许继续。
模板仓库的发布工作流要求标签与 package.json、package-lock.json 中的版本一致。请先提交所有待发布改动，再创建标签；标签推送成功不等于发布成功，还需检查发布工作流的结果。
release:archive 从 Git Tree 读取文件，不会把未提交内容放进压缩包。压缩包会排除 package-lock.json，并从 package.json 中去掉维护者使用的 commit 脚本。
模板仓库维护命令
npm run commit -- "提交说明" 仅存在于模板源码仓库的 scripts 中，发布源码包会移除它。它会暂存全部改动、准备下一个补丁版本、创建提交，并直接推送当前分支。未传入提交说明时会交互询问。