Cloudflare

更新于 2026年11月1日

Cloudflare Workers 可以直接提供静态资源目录：无需单独的计算资源，也无需 SPA 垫片。htmlpress.dev 就是这样发布的，同样结构的 wrangler.jsonc 适用于任何 htmlpress 站点。Workers 静态资源还会读取每次构建写出的 _headers 文件。

构建站点

htmlpress build

输出位于 .htmlpress/build/。

配置 `wrangler.jsonc`

将以下内容放在项目根目录：

{
  "name": "my-docs",
  "compatibility_date": "2026-04-01",
  "workers_dev": true,
  "assets": {
    "directory": ".htmlpress/build",
    "not_found_handling": "404-page",
  },
}

关键在于三个字段：

字段	作用
`assets.directory`	让 Wrangler 指向 htmlpress 的构建输出。每个文件都按原样提供。
`assets.not_found_handling`	用构建产出的 `404.html` 响应未知路径。
`workers_dev`	测试期间为你提供一个 `<name>.<account>.workers.dev` 预览 URL。

从本机部署

htmlpress build
npx wrangler deploy

首次运行时会提示执行 wrangler login，以授权访问你的 Cloudflare 账户。

使用 GitHub Actions 部署

name: deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx gethtmlpress build
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

在 My Profile → API Tokens 中创建一个限定范围的 API 令牌（“Edit Cloudflare Workers”模板恰好授予所需权限），并将这两个值存为仓库密钥。

如果不使用工作流，也可以让 Workers Builds 自行运行构建：在控制台中连接仓库，并在 wrangler.jsonc 中添加 build 块，htmlpress.dev 就是用 "build": { "command": "pnpm build:docs" } 这样做的。

自定义域名

当你的域名区域托管在 Cloudflare 上后，添加一个 routes 块：

{
  "name": "my-docs",
  "compatibility_date": "2026-04-01",
  "assets": { "directory": ".htmlpress/build", "not_found_handling": "404-page" },
  "routes": [{ "pattern": "docs.example.com", "custom_domain": true }],
}

custom_domain: true 让 Cloudflare 提供托管域名：DNS、证书和路由都会自动处理。在 htmlpress.yaml 中把 site 设为同一域名，使 sitemap 中的绝对 URL 保持一致。

htmlpress 仓库自带的 wrangler.jsonc 就是一个可用的参考；见项目根目录。

面向智能体的 Markdown

AI 智能体通过发送 Accept: text/markdown 来请求页面的 Markdown 版本。静态资源总是返回 HTML，因此需要为你的域名区域添加一条 URL 重写规则，把这些请求指向页面的 Markdown 副本：/guides/build/ 的 HTML 旁边就有 /guides/build/index.md。URL 重写规则在所有套餐（包括 Free）中均可使用，站点也仍然是完全静态的。

在控制台中打开你的域名，进入 Rules → Overview → Create rule → URL Rewrite Rule，然后填写：

字段	值
Rule name	`Markdown for agents`
If incoming requests match	Custom filter expression（见下文）
Path	Rewrite to → Dynamic → `concat(http.request.uri.path, "index.md")`
Query	Preserve

any(http.request.headers["accept"][*] contains "text/markdown") and ends_with(http.request.uri.path, "/")

页面 URL 以 / 结尾，因此该规则只作用于页面。静态资源会以 text/markdown 类型提供 .md 文件，因此响应类型无需额外规则。

请先部署包含 Markdown 副本的构建，再启用该规则。否则请求 Markdown 的智能体会得到 404。

另请参阅

AI 智能体：构建为智能体发布的内容。
站点元数据：site 用于生成绝对 URL 和 sitemap。
部署：返回托管平台索引。

用 ❤ 和 Htmlpress 构建