第 9 课：域名、免费部署与真实发布验收

1. 这一节解决什么问题

“本地能打开”不等于客户可访问。部署会暴露 Node 版本、SPA 直接访问 404、环境变量缺失、示例域名、缓存和 DNS 等问题。本节提供 Cloudflare Pages 主路线与 Netlify 备选路线，并把发布变成可回滚的验收过程。

2. 学完要拿到什么结果

• 一个公开 HTTPS 测试 URL。
• 配置正确的生产环境变量与 SPA 重写。
• 可选自定义域名和 DNS 记录清单。
• 一次外网路由、手机、SEO 和 RFQ 真链路验收。
• 发布记录、回滚点与交接说明。

3. 对应的开源对标及链接

• Cloudflare Pages Vite 官方指南：当前构建命令 npm run build，输出目录 dist，可连接 Git 仓库自动部署。
• Cloudflare Pages 概览：免费计划可用，具体限额以官方页面为准。
• Netlify Vite 官方指南：自动检测 Vite，常用构建为 npm run build、发布目录 dist；SPA 要配置重写。
• easy-vibe 部署章节：参考把平台选择、域名和表单纳入闭环的教学思想。

4. 完整图文课程正文

4.1 发布前冻结一个提交

先运行 check/build 和本地验收，创建 release: v1 demo acceptance 提交并记录哈希。部署的必须是这个提交。发布时不顺手改内容；线上发现问题，回本地修复、验证、提交再部署。

4.2 Cloudflare Pages 主路线

把仓库推到 GitHub。在 Cloudflare 控制台进入 Workers & Pages，选择创建应用、Pages、导入现有 Git 仓库。设置项目根目录为示范站目录（若仓库包含整个课程），构建命令 npm run build，输出 dist。添加 VITE_ 环境变量，再保存部署。每次推送生产分支会自动构建；非生产分支/PR 可得到预览部署，具体行为以控制台为准。

4.3 SPA 直接访问

React Router 使用干净 URL。服务器收到 /en/products/fresh-white-garlic 时必须返回 index.html，再由前端路由渲染。示范站提供 _redirects，规则为 /* /index.html 200，Cloudflare Pages 与 Netlify 都可使用。部署后要把详情 URL粘贴到新隐私窗口直接打开，不能只从首页点进去。

4.4 域名与 DNS

自定义域名是可选的，免费部署子域名已可验收。购买域名前确认注册人、续费价格、发票、备案/访问需求和品牌拼写。部署平台给出 CNAME/A/验证记录后，严格照抄主机名和值；DNS 生效可能需要时间。不要删除不理解的邮件 MX/TXT 记录，否则企业邮箱可能中断。

4.5 生产环境与示例数据

平台环境变量至少配置站点 URL、收件邮箱、WhatsApp 和 Web3Forms Key。重新构建后检查页面是否仍显示课程示范声明；如果用于真实企业，必须由企业签署内容确认单并替换示例信息，绝不能只删除标记而不补证据。

4.6 发布验收顺序

flowchart LR
  A[冻结提交] --> B[平台构建成功]
  B --> C[直接打开全部路由]
  C --> D[检查双语/手机/SEO]
  D --> E[线上提交 TEST RFQ]
  E --> F[邮箱收件]
  F --> G[记录证据和回滚点]

5. 零基础用户能够执行的操作步骤

1. 填写部署检查表，确认无密钥、示例状态明确、build 通过。
2. 把代码推到私有或公开 GitHub 仓库；公开前确认课程和代码许可证文件齐全。
3. 在 Cloudflare Pages 连接仓库，Root directory 指向 cases/garlic-b2b-website，Build command 填 npm run build，Output 填 dist。
4. 在平台设置添加 .env.example 所列生产变量；不要把值写在构建日志或课程截图中。
5. 等部署成功，记录生成的 pages.dev URL 和部署时间。
6. 新隐私窗口直接打开首页、3 个产品详情、公司、质量、市场、FAQ、联系的中英文 URL。
7. 检查 /robots.txt、/sitemap.xml，确认其中域名与生产域名一致；若静态文件需替换，先在本地改后重新部署。
8. 用手机网络打开页面并发送 [TEST] RFQ，确认邮件收件。
9. 需要自定义域名时，在平台添加域名，再按平台给出的 DNS 记录配置；保留现有 MX/TXT。
10. 填写网站最终验收表，保存部署 URL、提交哈希和回滚说明。

Netlify 备选：导入同一仓库，基础目录指向示范站，构建 npm run build、发布 dist，配置相同环境变量；public/_redirects 处理 SPA。

6. 可直接复制给 TRAE 或其他 AI 的提示词

请为当前 Vite + React Router 项目做“部署前只读审计”，不要部署、不要改线上状态。
检查：package scripts、Node 版本、构建输出、public/_redirects、robots.txt、sitemap.xml、VITE_SITE_URL、Web3Forms/邮箱/WhatsApp 环境变量、.gitignore、路由清单、示例数据标记、许可证。
输出 Cloudflare Pages 与 Netlify 的配置表：项目根目录、构建命令、输出目录、环境变量名、SPA 重写、上线后 URL 检查。
运行 npm run check 和 npm run build。若失败，只解释第一根因和最小修复；不得读取或打印 .env.local 的值。

7. 云南大蒜项目中的具体示范

示范发布记录格式：

• 站点：Yunnan Garlic B2B Course Demo（不是现实企业）。
• 发布提交：填真实 Git 哈希。
• 生产 URL：填平台实际生成 URL。
• 联系：rfq@example.com 与示例 WhatsApp 在未配置时不能冒充可用渠道。
• 内容状态：公司、产能、证书、市场、交期全部保留“示例数据，发布前需企业确认”。
• RFQ：使用测试邮箱与 [TEST] 内容；无商业意图。
• 回滚：平台回滚到上一次成功部署，或将生产分支恢复到上一已验证提交后重新部署。

8. 可填写模板

生产发布记录：

9. 常见错误

• 仓库根目录设置错，平台找不到 package.json。
• 构建输出填 build 而实际是 dist。
• 从首页点路由正常，刷新详情页却 404。
• 本地有 .env.local，平台没有同名环境变量。
• sitemap 仍写示例域名，或预览部署被搜索引擎收录。
• 配 DNS 时删除企业邮箱记录，造成邮件中断。

10. 排错方法

构建失败先看部署日志第一条实际错误，核对 Node 版本、根目录、锁文件和命令；不要连续改平台设置。详情刷新 404 检查 dist/_redirects 是否存在。环境变量改后需触发新构建。域名未生效用 DNS 查询核对平台要求的记录，等待 TTL；不要反复添加冲突记录。线上 RFQ 失败按第 8 课顺序检查 Network、响应、域名限制和收件规则。

11. 完成标准

• 部署的是有记录的已验证提交，HTTPS URL 可公开访问。

• 全部中英文路由可直接打开和刷新，无 404。

• 生产环境变量已配置但未泄漏。

• robots、sitemap、canonical 使用正式域名。

• 真实手机网络完成 [TEST] RFQ 并收到邮件。

• 有发布记录、验收人和可执行回滚方案。

12. 本节成果如何进入下一节

下一节把需求证据、PRD、源代码、测试、部署和验收整理为服务交付包：定义报价边界、客户责任、变更规则、培训和维护，而课程本身继续永久免费开放。

---

上一节：第 8 课：RFQ、SEO、测试与手机端验收
下一节：第 10 课：把一次开发整理成可报价、可交付的服务