本地安装

从 local-app 环境开始：使用 Next.js 开发、本地 SQLite 文件、密码登录、本地内容和基本账户资料。这一基础环境不需要 Cloudflare、OAuth、SMTP、支付、分析、CMS 或 DevReview 账户。选择核心组合可停止新销售。演示或 mock 结账不能用于真实购买，也不会授予付费访问权限。安装依赖仍需访问受信任的 npm 包。

环境	默认地址	用途
`local-app`	`http://localhost:3101`	快速 Next.js 开发与标准 Playwright 环境
`local-worker`	`http://localhost:8787`	可选的本地 Wrangler 运行时检查
`remote-cloudflare`	你自己的预览或生产域名	显式远端部署

安装你的模板副本

这是商业闭源开发者模板。请从提供给你的源码副本开始；公开预览不提供源码仓库访问权限。使用 Node.js 24 LTS、项目声明的 npm 10.9.2、Git，以及 macOS 或 Linux 上的 Bash。安装前检查 node --version 和 npm --version；Node 自带的 npm 可能与声明版本不同。在自己的源码副本根目录安装锁定的依赖：


npm ci

默认依赖图不需要私有 DevReview 包。保持锁文件完整性；校验和不匹配表示安装失败，不能用下载产物的校验和替换预期值来绕过检查。

创建本地环境文件之前，可运行项目维护的基础检查验证安装：


npm run test:baseline -- static
npm run test:baseline -- adoption

这些命令生成 Velite 内容、运行 lint 和类型检查，并构建 Next.js 与 Pagefind 搜索索引。检查使用合成配置，不需要数据库或供应商凭据。运行器要求 Node 24，并拒绝自动加载本地环境文件；如果已有本地配置，请使用独立检出目录。静态检查通过不能证明登录、数据库初始化、外部供应商或部署成功。运行 npm run test:baseline -- --help 查看各测试环境。

adoption 检查限于产品选择、保留的导航与已停用操作、运行时与诊断环境的一致性，以及诊断输出安全性。它使用合成输入，不联系外部供应商，也不运行完整应用测试套件。当前测试清单以维护中的运行器为准。认证指南的示例由 static 做类型检查；Better Auth 当前身份与撤销行为仍由 domain 验证。

配置 local-app

完成不依赖配置的基础检查后，复制公开示例：


cp .env.local.example .env.local

生成本地 Better Auth 密钥；以下命令不会自动修改环境文件：


node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

将生成值写入 .env.local，并保留这些本地设置：


APP_URL="http://localhost:3101"
AUTH_SECRET="your-generated-local-secret"
AUTH_TRUST_HOST="1"
DATABASE_URL="file:./dev.db"
PAYMENT_PROVIDER="mock"
DEV_AUTH_CODE="123456"

可选变量以 .env.example 为参考。本地数据库命令只读取 .env 与 .env.local，再应用 shell 覆盖值：默认值 < .env < .env.local < shell。显式为空的 DATABASE_URL 无效；未设置时默认为 file:./dev.db。

解析后的文件必须位于本项目目录内。远端 URL、越界路径、符号链接别名，以及任何非空的 CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_D1_DATABASE_ID 或 CLOUDFLARE_D1_TOKEN，都会在数据库写入前被拒绝。远端凭据应保存在各自环境的文件中；出现冲突时，检查提示的输入名称与来源。本地命令不会悄悄移除冲突凭据。

无副作用地检查配置

初始化数据库之前，在 src/config/product.ts 中选择应用组合，再从项目根目录运行只读接入诊断。核心部署使用 ...productCompositions.core；模板随附的真实购买选择在所需配置补齐前会报告阻塞：


npm run adoption:check -- --lane local-app

该命令读取所选环境的本地配置与唯一产品声明，不创建数据库、不检查数据库结构、不初始化记录、不启动应用、不加载供应商 SDK、不连接服务，也不部署。已有数据库文件保持不变。数据库不存在时仍报告 SCHEMA_UNVERIFIED，下一步为初始化。

场景	命令	结果
无配置查看接口	`npm run adoption:check -- --help`	显示帮助并退出 0，不导入或读取项目配置
检查 local-app 输入	`npm run adoption:check -- --lane local-app`	文本检查结果，包含安全的原因码和键名
检查 local-worker 输入	`npm run adoption:check -- --lane local-worker`	检查本地文件，实际 Worker 绑定仍未验证
以 JSON 检查预览输入	`TEMPLATE_ADOPTION_LANE=preview npm run --silent adoption:check -- --format json`	标准输出为一份 JSON，不连接远端
单次覆盖继承的环境选择	`TEMPLATE_ADOPTION_LANE=preview npm run adoption:check -- --lane production`	只检查生产环境的本地输入文件

--lane 接受 local-app、local-worker、preview 或 production，默认未设置。--format 接受 text 或 json，默认为 text。显式 CLI 选项覆盖 shell 中的 TEMPLATE_ADOPTION_LANE 与 TEMPLATE_ADOPTION_FORMAT，包括低优先级的无效值。这些选择器不会从环境文件加载。无参数且未设置选择器变量时显示帮助；只指定格式却未指定环境、使用未知选项或位置参数、选择器值无效或为空时，退出 2。--help 优先于所有其他输入。

环境	输入优先级，从低到高
`local-app`	领域默认值 → `.env` → `.env.local` → shell
`local-worker`	领域默认值 → `.dev.vars.dev` → shell
`preview`	领域默认值 → `.env.cloudflare.preview` → shell
`production`	领域默认值 → `.env.cloudflare` → shell

私有反馈上传需要 Assets 私有存储策略、独立私有 bucket 和 Images 绑定。公开 R2/S3 凭据不能证明这些条件就绪。选择附件后，普通 Node 诊断会报告缺失的私有绑定输入；缺少请求上下文的 Worker 环境仍为未知。运营观察可以描述当前私有绑定条件，但不探测远端存储，也不授予权限。停用新上传不会撤销历史附件的访问权限。

shell 提供所需输入时，环境文件可以不存在；文件不可读会产生 TOOL_FAILURE。接入要求 APP_URL 与非空 AUTH_SECRET。诊断与运行时共用纯声明 src/env/contract.ts，包括被检查的 NODE_ENV 对生产密钥的规则；诊断还应用 local-app 目标保护规则。即使能力已关闭或设置了 SKIP_ENV_VALIDATION，无效的可选设置仍是错误。真实结账需要受支持的 Stripe 配置；demo 当前不可用，也不授予付费能力。所选组合与已有客户义务见配置。

非本地环境检查上述文件，而非正在运行的 Worker 的实际环境。它们不会读取私有 Wrangler 绑定配置，也不会从凭据推断远端数据库或 bucket。已选择上传但缺少 Worker 上下文时仍为 unknown；公开 S3 输入不能使私有上传可用。DevReview 产物可信性、安装身份与适配器兼容性仍未验证；只有选择该集成后，才使用其独立预检。

理解检查结果与恢复

退出码	含义
`0`	未发现必需配置的已知阻塞，仍可能有 `unverified` 检查项
`1`	必需输入、本地目标或所选能力被阻塞
`2`	用法无效或工具无法完成检查

退出 0 不代表安装、数据库结构、登录、支付、应用或部署成功。 pass 只覆盖该检查项命名的声明或输入。能力状态与观察结果独立：disabled 表示未选择，blocked 表示已知缺失或无效输入，unknown 表示运行时上下文不足，available 表示该操作的配置充分。所有诊断观察仍是 unverified；即使 Mock 的 mode=demo 也不能证明支付或权益。这些状态描述所选配置，不代表用户权限，也不保证每个历史调用方都执行某个开关。

JSON 包含 schemaVersion: 1、lane、公开产品 revision、checks 与安全的运营 capabilities。自动化调用方必须拒绝不支持的结构版本。输出省略值、凭据、供应商 URL、绝对本地路径与原始异常；失败只包含受控代码、键名与来源类别。通过管道处理 JSON 时使用 npm 的 --silent，否则 npm 会输出自己的命令横幅。CLI 将工具或用法诊断写入 stderr；有效检查（包括退出 1）不产生 stderr 内容。用法错误没有 JSON 结果；选择器有效后发生工具失败，则输出带版本的失败结果。

nextStep 与 action 是标识符，不是插入密钥的命令：

下一步 ID	操作
`none`	此检查未指出需要修改
`configure-environment`, `inspect-input-files`	修正所选环境或 shell 覆盖中的指定输入；检查文件权限而不公开值
`review-local-target`	按上述 local-app 目标规则解决指定冲突
`verify-installation`	按公开基础检查步骤验证可信锁文件与安装
`initialize-local-schema`	按下文受保护的本地数据库初始化步骤操作
`verify-runtime-schema`, `verify-runtime`	按所选环境的显式配置、部署与运行时验证步骤操作
`configure-capability`, `select-checkout-mode`	对齐 `src/config/product.ts` 中的显式选择与领域输入
`verify-checkout`	验证配置支持的购买流程与原尝试恢复，再在销售前独立验证 Stripe
`devreview-preflight`	按下文可选 DevReview 的前提与 `integration:doctor -- --preflight` 操作

初始化本地数据库


npm run db:push
npm run db:seed -- --admin-action none

两个命令输出相同的规范化本地目标。db:push 使用已安装的 Drizzle migrator，按顺序应用 drizzle/ 迁移，包括数据回填和自定义约束。它接受空文件或匹配的 Drizzle 迁移历史。旧式仅推送结构所创建的数据库会被拒绝：保留原库，在全新迁移文件中演练数据转移，不要编造迁移历史。迁移前停止应用进程，完成后再启动。

Seed 只执行显式管理员操作。none 不写入并返回 skipped；create 创建缺失的管理员。它不创建演示计划、产品、报价或数据库结构。已有商业记录保持不变。

npm run db:init 先运行迁移，再按默认管理员意图运行 seed。若 seed 预检失败，先前的迁移可能已经提交。不支持 --force 或仅推送结构，因为两者都会绕过完整迁移合同。

显式创建管理员

选择与普通开发账户不同的邮箱，并加入 .env.local：


ADMIN_EMAIL="admin@example.test"
ADMIN_PASSWORD="choose-a-local-admin-password"

然后运行：


npm run db:seed -- --admin-action create

--admin-action 接受 none 或 create，覆盖 TEMPLATE_ADMIN_ACTION，默认值为 none。已有 ADMIN_EMAIL 却未显式指定操作时，seed 会在写入前以 ADMIN_INTENT_REQUIRED 失败；请有意选择 create，或显式指定 none 忽略管理员输入。没有默认管理员密码。

已有的活跃且未删除管理员返回 unchanged 与 PASSWORD_NOT_UPDATED。刚提供的密码不会被写入或验证。 请使用该账户原有密码登录。同邮箱的普通、停用或已删除账户会返回 ADMIN_CONFLICT，不会被覆盖。Seed 不提升用户权限、不重新激活账户、不重置密码，也不修改验证或资料字段。此类操作应走账户管理流程。

阅读结果与恢复

结果	含义与下一步
`succeeded` / 退出 0	所有请求步骤已完成或原本已存在；检查 `created`、`unchanged` 与 `skipped` 步骤
`failed` / 退出 1	预检或首次操作失败。`SCHEMA_REQUIRED` 表示需对同一目标执行结构步骤；`DB_BUSY` 可在其他本地写入者完成后重试
`partial` / 退出 1	前面步骤已完成，后续步骤失败；已写入内容保留，修复问题后重新运行以补齐记录
`unknown` / 退出 1，或进程中断且没有最终结果	写入可能已提交；对同一目标重新运行，以唯一键对齐已有记录，不要假定失败或重置数据库

管理员唯一性冲突不会覆盖已存在的记录。本地 db:seed 与 HTTP bootstrap 共用仅管理员、仅创建规则。HTTP 使用下述显式运营命令，不重置密码或提升已有用户权限。

通过 HTTP 初始化已运行的应用

迁移目标数据库并启动获授权的应用后，在所选私有辅助环境中配置 APP_URL 及其准确的 XADMIN_SECRET。db:seed:d1:local 读取 .dev.vars.dev，:preview 读取 .env.cloudflare.preview，db:seed:d1 读取 .env.cloudflare；shell 值覆盖这些文件。local-worker 命令要求 localhost HTTP(S) 目标。


# Explicit no-write initialization check:
npm run db:seed:d1:local -- initialize --admin-action none
# Explicit new administrator, using private ADMIN_EMAIL / ADMIN_PASSWORD inputs:
npm run db:seed:d1:preview -- initialize --admin-action create

不指定命令或使用 --help 时，只显示帮助，不读取环境文件或调用应用。没有默认管理员密码；HTTP 创建接受 8–128 字符的密码。已有活跃管理员保持不变，包括原密码。其他已有账户产生冲突且不修改。

辅助程序输出安全的步骤结果：退出 0 表示 succeeded，退出 2 保留 failed、partial 或 unknown，退出 1 表示配置、认证或无效/丢失传输。初始化不覆盖已有账户，也不创建商业目录。再次有意调用前应检查各步骤；辅助程序不会自动重试。HTTP 始终禁用缓存。

旧直接客户端必须发送 { "adminAction": "none" } 或 { "adminAction": "create", "adminEmail": "...", "adminPassword": "..." }。缺失或格式错误的请求体、未声明字段和无效凭据都会在写入前被拒绝。旧默认密码与覆盖行为已移除。

运行并验证 local-app

生成本地内容，再在选定端口启动应用：


npm exec velite
npm run dev:fast -- --port 3101

编辑本地博客内容后，重新运行 Velite，或在另一终端启动 npm exec velite -- --watch。保持 APP_URL 与实际端口一致。端口被占用时选择空闲端口并同时更新两者，不要停止无关服务。

打开首页与文档。选择新购买时再打开 /pricing；核心组合在此返回 404。
在 /register 创建 member@example.test 这样的普通账户。点击发送签发持久凭证，再在此非生产环境提交配置的 DEV_AUTH_CODE 与自选密码。密码登录使用已保存密码，不会自动创建账户。确认 /admin 拒绝访问。
退出登录或新建浏览器会话。使用单独显式初始化的管理员及其原有密码登录，确认可访问 /admin。旧会话不能证明当前数据库中的角色。
以普通用户打开 /me，修改显示名称并重新加载。确认已保存的名称和只读邮箱。基本资料修改不需要支付配置。
选择新购买时打开 /pricing；核心组合在此返回 404。演示或不可用的结账不创建付费权益；单独的价格回退卡片不能证明数据库初始化。真实销售需要已配置目录报价、已启用且受支持的供应商，以及独立验证的支付确认。

开发验证码只是非生产凭证 fixture，不能绕过密码登录。真实邮件注册、密码恢复和真实支付都需要各自配置并验证集成。

一次性浏览器检查

默认 Playwright 准备流程重建 e2e.db、安装 Chromium、应用数据库结构、显式创建管理员 fixture dev@example.com，并移除 .next、playwright-report 与 test-results。只有这些构建或报告目录没有被其他进程占用时才运行：


npm run test:e2e

准备流程在任何建目录、删除或浏览器安装前验证目标。仅接受 file:./e2e.db 或直接位于 .cache/e2e/ 下的命名 .db 文件；拒绝 dev.db、外部文件和符号链接目标。普通用户测试应使用不同邮箱。需要独立隔离的数据库时：


PW_E2E_DATABASE_URL="file:./.cache/e2e/adoption.db" npm run test:e2e

这个数据库文件是一次性的，准备时会被删除。远端运行时冒烟检查与 PW_E2E_REUSE_SERVER=1 有不同的准备职责，不能将其当作初始化证据。

可选：DevReview

公开基础配置保持 publicProductConfig.capabilities.devReview 为 false，无需私有包、密钥或适配器即可运行。只有取得可信、经过独立验证且带版本的产物后才能启用。验证来源与校验和后，将其安装到你自己的副本：


npm install --save-dev --save-exact /absolute/trusted/devreview-shared-VERSION.tgz /absolute/trusted/devreview-vite-plugin-VERSION.tgz

用审阅过的产物替换路径与版本，保留生成的 SHA-512 锁条目，后续安装使用 npm ci。不要复用已移除的原项目下载地址、编造校验和，或把下载到的校验和当作未知产物可信的证明。

按照 scripts/devreview-next.ts 中的 DevReviewNextAdapter 合同，提供导出 composeDevReview(config, target) 的 .devreview/next.cjs。根据已审阅 SDK 的实际 API 实现，并遵守传入的 projectId、serverUrl 与 applyInProduction。基础版本没有可信的私有 SDK，因此仓库不提供供应商适配器。

设置自己的 DEVREVIEW_PROJECT_ID 与 DEVREVIEW_SERVER_URL（HTTPS origin 或 loopback HTTP），再在 src/config/product.ts 中显式将 publicProductConfig.capabilities.devReview 设为 true。生产插桩默认 false；仅在有意启用时设置 DEVREVIEW_APPLY_IN_PRODUCTION=true。DEVREVIEW_API_TOKEN 只用于显式集成 CLI 操作，不传给构建适配器。

命令	效果
`npm run integration:doctor -- --preflight`	检查本地目标、锁定产物与适配器前提
`npm run integration:pack`	预检、构建，再检查清单
`npm run integration:doctor -- --remote`	本地检查后额外探测你的 bootstrap 端点
`npm run integration:bootstrap`	获取所选目标的 bootstrap 数据
`npm run manifest:upload -- [MANIFEST] [VERSION]`	将所选清单发布至选定的集成目标

这些命令的 --help 不读取项目环境；目标或产物前提缺失时，在网络 I/O 前拒绝。基础安装不能验证私有 SDK 兼容性或远端连通性。任何远端冒烟测试也需要显式提供你自己应用的 PW_BASE_URL。

可选：local-worker


cp .dev.vars.example .dev.vars.dev
npm run cf:preview

.dev.vars.dev 使用 APP_URL=http://localhost:8787；.env.local 保持用于 local-app。在 local-worker 自己的文件中设置 Better Auth、admin、cron 与 trigger 密钥。受版本控制的 custom-worker 拥有 Worker 运行时和定时行为。D1 绑定与独立的 local-worker 结构/seed 流程见配置指南。

npm run test:e2e:worker 检查已在 8787 运行的 Worker；npm run test:e2e:worker:headed 打开可见浏览器。两者都不会把默认 local-app 环境转换为 Worker 环境。

可选：远端 Cloudflare


cp wrangler.remote.example.toml wrangler.remote.toml
cp .env.cloudflare.example .env.cloudflare
cp .env.cloudflare.example .env.cloudflare.preview

将私有账户、路由和绑定写入 wrangler.remote.toml，远端辅助密钥写入 .env.cloudflare*，并遵循部署指南。受版本控制的 wrangler.toml 保持模板安全值。远端发布保留根目录 drizzle.config.ts；db:migrate、db:studio、远端发布与 db:seed:d1* 不在受保护 local-app 的保证范围内。

故障排查

目标冲突：检查 shell、.env.local 与 .env 中提示的 D1 输入，凭据应放在预期环境中。错误消息不显示凭据值。
缺少数据库结构：比较 push 与 seed 输出的目标，对同一文件运行 npm run db:push。不要通过删除已有数据库来排查连接错误。
已有管理员：PASSWORD_NOT_UPDATED 表示保留旧密码；向 seed 提供新密码不会重置密码。
依赖失败：解决报告的可信包或完整性问题后重新运行 npm ci。可选 DevReview 失败不要求基础配置启用该集成。
用法：npm run db:push -- --help 与 npm run db:seed -- --help 无需环境文件、数据库连接或供应商凭据。