使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接复制文档 Markdown 到剪贴板
import ReadMore from '/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
import StaticSsrTabs from '/components/tabs/StaticSsrTabs.astro';
你可以通过 Cloudflare Workers 和 Cloudflare Pages 来部署全栈应用，包括前端的静态资源和后端的 API，以及按需渲染站点。
本指南包含：
:::note
Cloudflare 更建议为新项目使用 Cloudflare Workers。对于现有的、使用 Pages 的项目，可参考 Cloudflare 的迁移指南 以及 compatibility matrix。
:::
阅读有关在 Astro 项目中 使用 Cloudflare 运行时 的更多内容。
前提条件
开始之前，你需要：
- 一个 Cloudflare 账号。如果你暂时还没有，可通过 Cloudflare 官网免费注册。
Cloudflare Workers
如何使用 Wrangler 进行部署
```bash npm install wrangler@latest --save-dev ```2. 如果你的站点使用了按需渲染，安装 @astrojs/cloudflare 适配器。
该步骤将会安装适配器，并对你的 `astro.config.mjs` 文件进行适当的调整。 ```bash npx astro add cloudflare ``` 接下来，在你的 `public/` 文件夹中创建一个 `.assetsignore` 文件，并向其添加以下内容： ```txt title="public/.assetsignore" _worker.js _routes.json ``` <ReadMore>阅读更多有关 [Astro 中的按需渲染](/zh-cn/guides/on-demand-rendering/)的内容。</ReadMore>3. 创建一个 Wrangler 配置项文件。
<StaticSsrTabs> <Fragment slot="static"> ```jsonc // wrangler.jsonc { "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", // 更新为今天的日期 "compatibility_date": "2025-03-25", "assets": { "directory": "./dist", "not_found_handling": "404-page" // 如果你有自定义的 `src/pages/404.astro` 页面 } } ``` </Fragment> <Fragment slot="ssr"> ```jsonc // 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 } } ``` </Fragment> </StaticSsrTabs>4. 使用 Wrangler 对你的项目进行本地预览。
```bash npx astro build && npx wrangler dev ```5. 使用 npx wrangler deploy 命令进行部署。
```bash npx astro build && npx wrangler deploy ```在你的资源上传之后，Wrangler 将会提供一个预览 URL 用以让你检视自己的网站。
阅读更多有关使用 Cloudflare 运行时 API 的内容，例如绑定。
如何使用 CI/CD 进行部署
你可以使用一个 CI/CD 系统，例如 Workers Builds (BETA) 来通过推送，自动化构建并部署你的网站。
假设你正在使用 Workers Builds：
-
登录至 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 进行部署
```bash npm install wrangler@latest --save-dev ```2. 如果你的站点使用了按需渲染，安装 @astrojs/cloudflare 适配器。
该步骤将会安装适配器，并对你的 `astro.config.mjs` 文件进行适当的调整。 ```bash npx astro add cloudflare ``` <ReadMore>阅读更多有关 [Astro 中的按需渲染](/zh-cn/guides/on-demand-rendering/) 的内容。</ReadMore>3. 使用 Wrangler 对你的项目进行本地预览。
```bash npx astro build && npx wrangler pages dev ./dist ```4. 使用 npx wrangler deploy 命令进行部署。
```bash npx astro build && npx wrangler pages deploy ./dist ```在你的资源上传之后，Wrangler 将会提供一个预览 URL 用以让你检视自己的网站。
如何使用 Git 来部署站点
-
登录至 Cloudflare dashboard 并导航至 Compute (Workers) > 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:* 的导入语法。如果不支持，你可能需要找到一个替代的包。