部署你的 Astro 站点至 Cloudflare

你可以通过 Cloudflare Workers 来部署全栈应用，包括前端的静态资源和后端的 API，以及按需渲染站点。

阅读有关在 Astro 项目中使用 Cloudflare 运行时 (EN) 的更多内容。

前提条件

开始之前，你需要：

一个 Cloudflare 账号。如果你暂时还没有，可通过 Cloudflare 官网免费注册。

Cloudflare Workers

如何使用 Wrangler 进行部署

安装 Wrangler CLI。
终端窗口
```
npm install wrangler@latest --save-dev
```
如果你的站点使用了按需渲染，安装 @astrojs/cloudflare 适配器 (EN)。

该步骤将会安装适配器，并对你的 astro.config.mjs 文件进行适当的调整。
- npm
- pnpm
- Yarn
终端窗口
npx astro add cloudflare
终端窗口
pnpm astro add cloudflare
终端窗口
yarn astro add cloudflare
阅读更多有关 Astro 中的按需渲染的内容。
创建一个 Wrangler 配置项文件。

运行 astro add cloudflare 将会为你创建此文件；如果你没有使用适配器，则需要自行创建。
- 静态
- SSR
wrangler.jsonc
{ "name": "my-astro-app", "compatibility_date": "YYYY-MM-DD", // 更新为你部署当天的日期 "assets": { "directory": "./dist", } }
wrangler.jsonc
{ "main": "dist/_worker.js/index.js", "name": "my-astro-app", "compatibility_date": "YYYY-MM-DD", // 更新为你部署当天的日期 "compatibility_flags": [ "nodejs_compat", "global_fetch_strictly_public" ], "assets": { "binding": "ASSETS", "directory": "./dist" }, "observability": { "enabled": true } }
使用 Wrangler 对你的项目进行本地预览。
终端窗口
```
npx astro build && npx wrangler dev
```
使用 npx wrangler deploy 命令进行部署。
终端窗口
```
npx astro build && npx wrangler deploy
```

在你的资源上传之后，Wrangler 将会提供一个预览 URL 用以让你检视自己的网站。

阅读更多有关使用 Cloudflare 运行时 API (EN) 的内容，例如绑定。

如何使用 CI/CD 进行部署

你可以使用一个 CI/CD 系统，例如 Workers Builds 来通过推送，自动化构建并部署你的网站。

假设你正在使用 Workers Builds：

与上文中如何使用 Wrangler 进行部署的步骤 1-3 相同。
登录至 Cloudflare dashboard 并导航至 Compute > Workers & Pages 页面。选择 Create application（创建应用）。
在 Import a repository（导入仓库）选项下，选择一个 Git 账号，然后选择包含你 Astro 项目的仓库。
配置项目：
- Build command（构建命令）：npx astro build
- Deploy command（部署命令）：npx wrangler deploy
点击 Save and Deploy（保存并部署）。你现在可以在它提供的 workers.dev 子域名下，预览 Worker 部署的结果了。

故障排除

404 行为

对于 Workers 项目，如果你想使用自定义 404 页面，则需要设置 not_found_handling。你可以在 Cloudflare 文档的 Routing behavior 部分了解更多信息。

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

客户端 hydration

由于 Cloudflare 的 Auto Minify（自动压缩）功能，客户端 Hydration 可能会失败。如果你在控制台中看到 Hydration completed but contains mismatches，请确保在 Cloudflare 设置中禁用 Auto Minify。

Node.js 运行时 API

如果你正在构建一个使用 Cloudflare 适配器 (EN) 的按需渲染项目，并且服务器在构建时失败，出现如 [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node. 的错误信息：

这意味着你在服务器端环境中使用的某个包或导入项与 Cloudflare 运行时 API 不兼容。
如果你直接导入了一个 Node.js 运行时 API，请参考 Astro 关于 Cloudflare 的 Node.js 兼容性 (EN) 文档，了解如何解决这个问题的进一步步骤。
如果你导入的包中包含了 Node.js 运行时 API，请检查该包的作者是否支持 node:* 的导入语法。如果不支持，你可能需要找到一个替代的包。