部署你的 Astro 站点至 Cloudflare

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

本指南包含：

如何部署至 Cloudflare Workers
如何部署至 Cloudflare Pages

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

前提条件

开始之前，你需要：

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

Cloudflare Workers

如何使用 Wrangler 进行部署

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

该步骤将会安装适配器，并对你的 astro.config.mjs 文件进行适当的调整。
终端窗口
```
npx astro add cloudflare
```
接下来，在你的 public/ 文件夹中创建一个 .assetsignore 文件，并向其添加以下内容：
public/.assetsignore
```
_worker.js
_routes.json
```
阅读更多有关 Astro 中的按需渲染的内容。
创建一个 Wrangler 配置项文件。
- 静态
- SSR
wrangler.jsonc
{ "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", // 更新为今天的日期 "compatibility_date": "2025-03-25", "assets": { "directory": "./dist" } }
wrangler.jsonc
{ "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", "main": "./dist/_worker.js/index.js", // 更新为今天的日期 "compatibility_date": "2025-03-25", "compatibility_flags": ["nodejs_compat"], "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 的内容，例如绑定。

如何使用 CI/CD 进行部署

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

假设你正在使用 Workers Builds：

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

Cloudflare Pages

如何使用 Wrangler 进行部署

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

该步骤将会安装适配器，并对你的 astro.config.mjs 文件进行适当的调整。
终端窗口
```
npx astro add cloudflare
```
阅读更多有关 Astro 中的按需渲染的内容。
使用 Wrangler 对你的项目进行本地预览。
终端窗口
```
npx astro build && npx wrangler pages dev ./dist
```

使用 npx wrangler deploy 命令进行部署。

npx astro build && npx wrangler pages deploy ./dist

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

如何使用 Git 来部署站点

推送代码至 Git 仓库（例如：GitHub、GitLab）。
登录至 Cloudflare dashboard 并导航至 Workers & Pages。选择 Create（创建）并选择 Pages。连接至你的 Git 仓库。
配置项目：
- Framework preset（框架预设）：Astro
- Build command（构建命令）：npm run build
- Build output directory（构建输出目录）：dist
点击 Save and Deploy（保存并部署） 按钮。

故障排除

客户端 hydration

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

Node.js 运行时 API

如果你正在构建一个使用 Cloudflare 适配器的按需渲染项目，并且服务器在构建时失败，出现如 [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 兼容性文档，了解如何解决这个问题的进一步步骤。
如果你导入的包中包含了 Node.js 运行时 API，请检查该包的作者是否支持 node:* 的导入语法。如果不支持，你可能需要找到一个替代的包。