本地运行

进入项目根目录，可以看到当前 Saavo 默认模板的主要结构。下面只省略了 node_modules、构建产物和本地运行缓存：

刚开始开发时，先记住几个位置：config/ 保存产品和功能配置，src/pages/ 与 src/api/ 分别放页面和接口，src/core/ 放业务逻辑，content/ 和 locales/ 管理内容与国际化。.env 只用于本地环境，Cloudflare 绑定和 Worker 配置在 wrangler.jsonc 中。

启动本地开发服务器：

cd my-project
npm run dev

启动前会生成文档搜索索引，随后由 Vite 和 Cloudflare 插件拉起本地 Workers 运行时。终端会显示实际访问地址，通常是：

http://127.0.0.1:5173

如果端口被占用，Vite 会换到其它端口。浏览器地址和本地 VITE_SITE_URL 都以终端输出为准，不要认定只能使用 5173。

先做一次最小检查

打开终端给出的地址，依次确认：

• 首页能够正常显示；
• /docs 可以打开；
• 登录和注册页面能够进入；
• 刷新页面后没有出现数据库缺表或 Binding 缺失错误。

本地数据库在创建项目时已经初始化，不需要另开终端执行 wrangler d1 execute。想再次检查环境，可以运行：

npm run doctor

doctor 可能提示 Resend、Stripe 或 OAuth 尚未配置。只要输出中没有 ERROR，这些暂未使用的服务不影响继续开发。

本地环境和生产环境分开

本地开发只读取 .env。默认情况下：

• SAAS_SECRET 已由 saavo:init 生成；
• Turnstile 使用 Cloudflare 测试密钥；
• Resend、Stripe、GitHub 和 Google 等凭据可以留空；
• D1、KV、R2、Queue 和 Durable Objects 由本地 Workers 运行时模拟。

修改 .env 后需要重启 npm run dev。生产环境使用的密钥不要提前塞进 .env，首次部署时会把它们写入 .env.production。

初始化没有完成怎么办

如果终端提示缺少 .env、SAAS_SECRET、数据库表或生成类型，先停止开发服务器，再运行：

npm run saavo:init
npm run dev

日常新增数据库迁移时使用 npm run db:migrate:local。只有确定本地数据可以全部删除时，才使用 npm run db:reset:local；它不是普通的修复命令。

部署前先决定配置到什么程度

如果只是验证部署链路，可以先保留大部分模板内容。Turnstile 可以暂时使用 Cloudflare 官方测试密钥；邮件按照当前选择的服务准备所需密钥，以及自己的发件人与客服邮箱。Stripe、GitHub 登录和 Google 登录没有准备好时，可以继续跳过。

真正面向用户之前，还应按实践部分的说明修改品牌、产品、价格、管理员邮箱和法律页面。快速开始只保证项目能运行和部署，不代表模板默认内容可以直接作为你的产品发布。

下一页：首次部署。