将你的 Astro 网站部署到 Cloudflare

你可以将全栈应用程序（包括前端静态资源和后端 API）以及按需渲染的网站部署到 Cloudflare Workers 和 Cloudflare Pages。

本指南包括

如何部署到 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 配置文件。
- 静态
- 按需渲染模式
wrangler.jsonc
{ "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", // Update to today's date "compatibility_date": "2025-03-25", "assets": { "directory": "./dist", "not_found_handling": "404-page" // If you have a custom `src/pages/404.astro` page } }
wrangler.jsonc
{ "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", "main": "./dist/_worker.js/index.js", // Update to today's date "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 仪表盘并导航到 Workers & Pages。选择 Create。
在 Import a repository 下，选择一个 Git 帐户，然后选择包含你的 Astro 项目的仓库。
使用以下配置你的项目
- 构建命令：npx astro build
- 部署命令：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 仪表盘并导航到 Compute (Workers) > Workers & Pages。选择 Create，然后选择 Pages 选项卡。连接你的 git 仓库。
使用以下配置你的项目
- 框架预设：Astro
- 构建命令： npm run build
- 构建输出目录： dist
点击 Save and Deploy 按钮。

故障排除

客户端激活

由于 Cloudflare 的 Auto Minify（自动压缩）设置，客户端激活可能会失败。如果你在控制台中看到 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:* 导入语法。如果不支持，你可能需要寻找替代的包。