# 23 - Cloudflare Pages 推送实践与链接治理

更新时间：2026-05-29 Asia/Shanghai

## 1. 一句话结论

```text
由 Codex 辅助发布 Cloudflare Pages，最佳路径是：site/ 白名单发布目录 + Wrangler CLI + 环境变量密钥 + 后续 Git 集成。
```

## 2. 推荐实践

当前阶段使用 Wrangler Direct Upload：

```text
本地源文件 -> scripts/build-cloudflare-pages-site.sh -> site/ -> wrangler pages deploy -> Cloudflare Pages
```

已准备脚本：

```text
scripts/build-cloudflare-pages-site.sh
scripts/deploy-cloudflare-pages.sh
cloudflare-pages.env.example
wrangler.toml
```

当更新频率变高时，再接 GitHub/GitLab。Cloudflare 官方 Git integration 支持连接 GitHub/GitLab repository，并在 push 到分支时自动部署。

## 3. Codex 帮你部署的条件

### 方式 A：API Token，推荐

你在本机 shell 中设置：

```bash
export CLOUDFLARE_ACCOUNT_ID="..."
export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_PAGES_PROJECT_NAME="ecommerce-research-portal"
```

然后我可以运行：

```bash
scripts/deploy-cloudflare-pages.sh
```

注意：不要把真实 token 写入项目文件。`cloudflare-pages.env.example` 只放占位符。

### 方式 B：Wrangler Login

你本机先执行：

```bash
npx wrangler login
```

登录后，我可以运行部署脚本。但这种方式在自动化和 Codex 环境中不如 API Token 稳定。

## 4. 链接治理规则

### 公开 URL 使用英文 slug

源文件可以保持中文名，但发布到 `site/` 时使用英文 slug。

| 源文件 | 发布文件 |
|---|---|
| 美国公司设立与税务预检.html | us-company-tax-precheck.html |
| 美国公司触发条件与实体选择决策树.html | us-company-decision-tree.html |
| 营业额梯度触发权重模型.html | revenue-trigger-model.html |
| 创业伙伴研究共享方案.html | partner-research-sharing.html |
| 共享层策略与HTML发布判断.html | sharing-layer-html-publishing.html |
| Cloudflare-Pages推送实践与链接治理.html | cloudflare-pages-deploy-practice.html |

原因：中文文件名本身可以工作，但英文 slug 更适合公网 URL、Notion 粘贴、伙伴转发和未来自定义域名。

### Atlas 中不再链接本地 Markdown

`research-atlas-cytoscape.html` 原本会链接 `research/*.md`。这些源文档不在 `site/` 白名单发布目录中，因此发布版会把 Markdown 链接降级为提示：

```text
源文档请见 Notion / 本地仓库
```

这样避免公网 404，也避免误发布源仓库。

## 5. 不发布什么

不要把以下内容放进 `site/`：

- 公司证件
- 身份证明
- 支付账户后台
- 银行资料
- 合同
- 具体利润和资金流水
- 未公开商品方向
- 供应链资源
- Cloudflare API Token 或任何密钥

## 6. 证据入口

- Cloudflare Wrangler Pages commands: https://developers.cloudflare.com/workers/wrangler/commands/pages/
- Cloudflare Direct Upload with CI: https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/
- Cloudflare Pages Git integration: https://developers.cloudflare.com/pages/configuration/git-integration/

## 8. 2026-05-29 部署试运行结果

第一次部署试运行结果：

- Node/npm 已通过 Homebrew 安装完成。
- Wrangler 已能通过 `npx wrangler` 启动。
- 部署未完成，原因是 Codex 执行环境中没有读取到 `CLOUDFLARE_API_TOKEN`。

已补充脚本能力：

- `scripts/deploy-cloudflare-pages.sh` 会自动读取项目根目录下的 `.cloudflare-pages.env`。
- `.cloudflare-pages.env` 已加入 `.gitignore`，用于本地保存 Cloudflare token，不应共享或提交。

推荐本地文件格式：

```bash
export CLOUDFLARE_ACCOUNT_ID="your_cloudflare_account_id"
export CLOUDFLARE_API_TOKEN="your_cloudflare_api_token"
export CLOUDFLARE_PAGES_PROJECT_NAME="ecommerce-research-portal"
```

## 9. Pages 部署成功后的 Notion 回填规则

当前不配置自定义域名，直接使用 Cloudflare Pages 默认的 `*.pages.dev` 链接。

部署成功后，需要回填以下 Notion 页面：

- 伙伴入口页：把 HTML 共享入口链接更新为 Pages 首页链接。
- 研究共享索引：把本地 HTML 文件名旁边补充 Pages URL。
- Cloudflare Pages HTML 发布层方案：记录当前生产链接。
- Cloudflare Pages 推送实践与链接治理：记录最近一次部署链接和部署状态。

当前原则：

```text
先使用 *.pages.dev
暂不启用自定义域名
暂不配置复杂访问控制
不把敏感资料发布到 site/
```

自定义域名触发条件：

- 伙伴访问频率变高。
- 项目进入长期协作阶段。
- 需要更稳定、更品牌化的共享入口。
- 已明确哪些内容可以公开或半公开。

## 10. 2026-05-29 部署成功记录

Cloudflare Pages 已部署成功。

- Project：`ecommerce-research-portal`
- 生产入口：https://ecommerce-research-portal.pages.dev/
- 本次部署预览：https://f21d3df9.ecommerce-research-portal.pages.dev
- 上传文件数：18
- 域名策略：暂不配置自定义域名，使用 Cloudflare 默认 `*.pages.dev`

已回填 Notion：

- 伙伴入口页
- 研究共享索引
- Cloudflare Pages HTML 发布层方案
- Cloudflare Pages 推送实践与链接治理

## 11. 2026-06-03 Markdown 源文档发布规则

根据伙伴可读性需求，Markdown 源文档也纳入 Cloudflare Pages 发布层。

执行方式：

- 不直接发布整个 `research/` 目录。
- 使用白名单复制当前可共享 Markdown 到 `site/research/`。
- 生成 `site/research/index.html` 作为 Markdown 研究文档索引。
- Atlas 发布版恢复对 `research/*.md` 的可点击链接。

发布入口：

```text
https://ecommerce-research-portal.pages.dev/research/index.html
```

边界：后续如出现敏感 Markdown，不自动加入白名单。

## 12. 2026-06-03 Markdown 源文档部署成功记录

Cloudflare Pages 已重新部署成功，Markdown 源文档已上线。

- Markdown 文档索引：https://ecommerce-research-portal.pages.dev/research/index.html
- 本次部署预览：https://b44c0471.ecommerce-research-portal.pages.dev
- 上传统计：40 个文件，其中 29 个新上传，11 个已存在

已回填 Notion：

- 伙伴入口页
- 研究共享索引
- Cloudflare Pages 推送实践与链接治理

## 13. 2026-06-03 选品方法论专题部署记录

Cloudflare Pages 已重新部署成功，选品方法论专题已上线。

- HTML 专题页：https://ecommerce-research-portal.pages.dev/product-research-methodology.html
- Markdown 源文档：https://ecommerce-research-portal.pages.dev/research/25-选品调研方法论与技术实现路线.md
- 本次部署预览：https://7bc642c0.ecommerce-research-portal.pages.dev
- 上传统计：43 个文件，其中 8 个新上传，35 个已存在

## 14. 2026-06-03 选品交付流水线专题部署记录

Cloudflare Pages 已重新部署成功，选品交付流水线专题已上线。

- HTML 专题页：https://ecommerce-research-portal.pages.dev/product-research-delivery-pipeline.html
- Markdown 源文档：https://ecommerce-research-portal.pages.dev/research/26-选品交付流水线与结果模板.md
- 本次部署预览：https://b6d3b505.ecommerce-research-portal.pages.dev
- 上传统计：45 个文件，其中 8 个新上传，37 个已存在