# Cloudflare

> 通过 Cloudflare Workers 静态资源部署——htmlpress.dev 本身采用的方案。

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

## 构建站点

```sh
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。 |

## 从本机部署

```sh
htmlpress build
npx wrangler deploy
```

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

## 使用 GitHub Actions 部署

```yaml
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` 就是一个可用的参考；见 [项目根目录](https://github.com/datisthq/htmlpress/blob/main/wrangler.jsonc)。

## 面向智能体的 Markdown

AI 智能体通过发送 `Accept: text/markdown` 来请求页面的 Markdown 版本。静态资源总是返回 HTML，因此需要为你的域名区域添加一条 URL 重写规则，把这些请求指向页面的 [Markdown 副本](/zh/customization/ai-agents/)：`/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` 文件，因此响应类型无需额外规则。

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

## 另请参阅

- [AI 智能体](/zh/customization/ai-agents/)：构建为智能体发布的内容。
- [站点元数据](/zh/customization/site-metadata/)：`site` 用于生成绝对 URL 和 sitemap。
- [部署](/zh/deployment/)：返回托管平台索引。