05. 绑定域名和环境变量

这一章解决的是：把“能跑起来”的系统，变成“真正可上线”的系统。

如果你不绑定正式域名，系统可能也能工作，但会有这些问题：

*.workers.dev / *.pages.dev 地址不适合作为正式品牌地址
Stripe、Creem 等支付回调需要公网可访问的正式地址
sitemap、canonical、robots 不应该长期指向临时预览域名

node3-pay-service 必须优先绑定域名，否则支付 webhook 通常无法可靠到达。

1. 绑定正式域名

Web（Astro 6）

web 当前部署到 Worker，不是 Pages。
请在 Cloudflare Dashboard -> Workers & Pages -> 目标 Worker -> Settings -> Domains & Routes 中绑定正式域名。

推荐做法：把 apps/web 当模板，不要直接改它；复制成你自己的项目后再继续开发。

如果你是复制 `apps/web` 来创建新站

现在的正确顺序是：

先在 Admin 里创建租户
- 打开 Admin -> Projects
- 新建一条项目记录
- 填写唯一的 app_key
- 这一步才算在后端真正注册了租户
复制 apps/web
- 例如复制成 apps/my-brand
修改 apps/my-brand/zship.app.json
- appKey：必须和 Admin 里刚创建的 app_key 一致
- domain：正式域名
- siteUrl：正式站点 URL
- pagesProject：这个前端应用自己的部署目标名
- siteName、brand.name、brand.logo：品牌字段
确认运行时环境变量一致
- 当前前端运行时仍然会读取 APP_KEY
- Dev Console 会把 manifest 同步到 .env，但运行时代码本身还没有完全去掉 env 依赖
修改 wrangler.toml 的 name
- 这一步非常重要
- 如果你复制完还是 name = "web"，部署时很可能覆盖原来的 web Worker
为新站绑定自己的域名
- 不要直接复用原来的 web 域名，除非你就是要替换原站
重新部署这个新前端
- 它应该作为一个独立站点部署，而不是继续落到原来的 web 上

一句话记忆：

Admin 负责创建租户
zship.app.json 负责声明“这个前端对应哪个租户”
wrangler.toml 负责声明“这个前端到底部署到哪个 Worker”

Admin

admin 一般部署在 Pages。
请在 Workers & Pages -> admin -> Custom domains 中绑定域名。

后端 Worker

优先绑定 node3-pay-service，因为它要接收支付回调。其他 Worker 可按需绑定。

CDN 和 R2（`CDN_PUBLIC_URL`）

如果你使用 node6-cdn-service 上传文件，Worker 中的 CDN_PUBLIC_URL 必须与 R2 bucket 的自定义域名一致。否则常见现象是“上传成功，但访问 URL 返回 404”。完整说明见上线排查。

2. 前端环境变量、`site.ts` 和 `zship.app.json` 的关系

现在前端配置是分层的，不是“只改一个地方就够”。

zship.app.json
- 现在推荐作为前端项目的主配置源
- 管理 appKey、siteUrl、domain、品牌信息、部署项目名等
site.ts
- 仍然是前端代码运行时会读取的展示配置文件
- Dev Console 会把 manifest 同步到这里
环境变量
- 本地在 .env
- 线上在 Cloudflare Variables / Secrets
- 当前前端运行时仍然会读取 APP_KEY、SITE_URL 和服务 URL

所以当前的正确理解是：

平时你优先改 zship.app.json
Dev Console 负责把它同步到 site.ts / .env
前端运行时依旧会读取 env

3. Canonical URL 和 Latest deployed URL 不是一回事

不要把这两个概念混在一起：

Canonical URL：正式站点 URL，例如 https://my-brand.com
Latest deployed URL：最近一次部署得到的预览地址，例如 https://xxxx.my-brand.pages.dev

当前约定是：

zship.app.json 里的 siteUrl 是 Canonical URL
SITE_URL 应该跟随这个 canonical URL
部署过程中发现的 pages.dev 地址只是 Latest deployed URL，不能反过来覆盖 sitemap、canonical、robots 这些正式元数据

4. 建议填写哪些前端变量

为复制后的 web 项目配置变量时，通常至少会涉及：

APP_KEY=my-brand
SITE_URL=https://my-brand.com
AUTH_SERVICE_URL=https://n1.example.com
PAY_SERVICE_URL=https://n3.example.com
BLOG_API_URL=https://n5.example.com
SITE_SERVICE_URL=https://n7.example.com
CHECKIN_SERVICE_URL=https://n9.example.com
AI_SERVICE_URL=https://n10.example.com
SUPPORT_SERVICE_URL=https://n2.example.com

其中：

APP_KEY 必须和 Admin 租户一致
SITE_URL 应该是正式域名，不是临时的 pages.dev

5. 改完变量后要重新部署

环境变量、域名或前端身份改完以后，需要重新部署前端，否则旧值可能仍然保留在构建产物中。

6. 最后做一次快速检查

上线前至少确认：

能打开正式站点域名
能打开 admin 域名
登录和注册走的是正确租户
前端请求打到了正式后端地址
sitemap、robots、canonical 指向的是正式域名，而不是 pages.dev