将你的 Astro 站点部署到 Cloudflare Pages

你可以在 Cloudflare Pages 上部署 Astro 项目，Cloudflare Pages 是前端开发者协作和部署静态 (JAMstack) 和 SSR 网站的平台。

¥You can deploy your Astro project on Cloudflare Pages, a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites.

本指南包括：

¥This guide includes:

如何通过 Cloudflare Pages Dashboard 进行部署
如何使用 Wrangler、Cloudflare CLI 进行部署
如何使用 @astrojs/cloudflare 部署 SSR 站点

先决条件

¥Prerequisites

首先，你将需要：

¥To get started, you will need:

Cloudflare 账户。如果你还没有，你可以在此过程中创建一个免费的 Cloudflare 账户。
你的应用代码已推送到 GitHub 或 GitLab 存储库。

如何使用 Git 部署站点

¥How to deploy a site with Git

Set up a new project on Cloudflare Pages.
Push your code to your git repository (GitHub, GitLab).
Log in to the Cloudflare dashboard and select your account in Account Home > Workers & Pages > Overview.
Select Create application, then the Pages tab and then select the Connect to Git option.
Select the git project you want to deploy and click Begin setup
Use the following build settings:
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
Click the Save and Deploy button.

如何使用 Wrangler 部署站点

¥How to deploy a site using Wrangler

Install Wrangler CLI.
Authenticate Wrangler with your Cloudflare account using wrangler login.
Run your build command.
Deploy using npx wrangler pages deploy dist.

# Install Wrangler CLI
npm install -g wrangler
# Login to Cloudflare account from CLI
wrangler login
# Run your build command
npm run build
# Create new deployment
npx wrangler pages deploy dist

上传资源后，Wrangler 将为你提供一个预览 URL 以检查你的网站。当你登录 Cloudflare Pages 仪表板时，你将看到你的新项目。

¥After your assets are uploaded, Wrangler will give you a preview URL to inspect your site. When you log into the Cloudflare Pages dashboard, you will see your new project.

使用 Wrangler 在本地启用预览

¥Enabling Preview locally with Wrangler

要使预览版正常工作，你必须安装 wrangler

¥For the preview to work, you must install wrangler

pnpm add wrangler --save-dev

然后可以更新预览脚本以运行 wrangler 而不是 Astro 的内置预览命令：

¥It’s then possible to update the preview script to run wrangler instead of Astro’s built-in preview command:

"preview": "wrangler pages dev ./dist"

如何部署 SSR 站点

¥How to deploy an SSR site

你可以使用 @astrojs/cloudflare 适配器构建一个 Astro SSR 站点以部署到 Cloudflare Pages。

¥You can build an Astro SSR site for deployment to Cloudflare Pages using the @astrojs/cloudflare adapter.

请按照以下步骤设置适配器。然后，你可以使用上述任一方法进行部署。

¥Follow the steps below to set up the adapter. You can then deploy using either of the approaches documented above.

快速安装

¥Quick install

使用以下 astro add 命令添加 Cloudflare 适配器以在 Astro 项目中启用 SSR。这将一步安装适配器并对 astro.config.mjs 文件进行适当的更改。

¥Add the Cloudflare adapter to enable SSR in your Astro project with the following astro add command. This will install the adapter and make the appropriate changes to your astro.config.mjs file in one step.

npx astro add cloudflare

手动安装

¥Manual install

如果你更愿意手动安装适配器，请完成以下两个步骤：

¥If you prefer to install the adapter manually instead, complete the following two steps:

Add the @astrojs/cloudflare adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal:
Terminal window
```
npm install @astrojs/cloudflare
```

Add the following to your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare()
});

故障排除

¥Troubleshooting

客户端水合

¥Client-side hydration

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

¥Client-side hydration may fail as a result of Cloudflare’s Auto Minify setting. If you see Hydration completed but contains mismatches in the console, make sure to disable Auto Minify under Cloudflare settings.

Node.js 运行时 API

¥Node.js runtime APIs

如果你正在构建使用 Cloudflare SSR 适配器进行按需渲染的项目，并且服务器无法构建并显示错误消息（如 [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.）：

¥If you are building a project that is using on-demand rendering with the Cloudflare SSR adapter and the server fails to build with an error message such as [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:* 导入语法。如果没有，你可能需要寻找替代包。