部署你的 Astro 站点至 Cloudflare Pages

你可以将你的 Astro 项目部署在 Cloudflare Pages 上。Cloudflare Pages 是一个供前端开发人员协作和部署静态 (JAMstack) 或 SSR 网站的平台。

本指南包含：

如何使用 Git 部署一个站点
如何使用 Wrangler 部署一个站点
如何部署 SSR 站点

前提条件

开始之前，你需要：

一个 Cloudflare 账号。如果你暂时还没有，你可以现在免费去 Cloudflare 官网注册一个。
你的源代码存储在一个 GitHub 或者 GitLab 仓库里。

如何使用 Git 部署一个站点

在 Cloudflare Pages 设置一个新项目。
将你的代码提交到一个 Git 仓库中 (GitHub, GitLab)。
登录 Cloudflare Dashboard 并在 Account Home > Workers & Pages > Overview 选择你的账号。
选择 Create application，然后选择 Pages 标签页，接着选择 Connect to Git 选项。
选择你想部署的 Git 项目并点击 Begin setup（初始设置）。
使用以下的构建设置：
- Framework preset（框架预设）: Astro
- Build command（构建命令）: npm run build
- Build output directory（构建输出目录）: dist
点击 Save and Deploy（保存并部署）按钮。

如何使用 Wrangler 部署一个站点

安装 Wrangler CLI。
使用 wrangler login 在 Wrangler 登录 Cloudflare 账号并授权。
运行你的构建命令（比如 npm run build）。
使用 npx wrangler pages deploy dist 进行部署。

# 安装 Wrangler CLI（命令行）
npm install -g wrangler
# 在 CLI 中登录 Cloudflare 账号
wrangler login
# 运行你的构建命令
npm run build
# 创建新的部署
npx wrangler pages deploy dist

上传完所有的文件后，Wrangler 将为你提供一个预览 URL 以检查你的站点。当你登录 Cloudflare Pages 仪表板时，你将看到你的新项目。

使用 Wrangler 在本地启用预览

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

pnpm add wrangler --save-dev

然后就可以将预览脚本从 Astro 的内置预览命令更新为 wrangler 了：

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

如何部署 SSR 站点

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

请按照以下步骤设置适配器。完成后，你可以使用上述文档中的任何方法进行部署。

快速安装

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

npx astro add cloudflare

手动安装

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

使用你喜欢的包管理器将 @astrojs/cloudflare 添加到项目的依赖项中。如果你正在使用 npm 或不确定是哪个包管理器，请在终端中运行：
终端窗口
```
npm install @astrojs/cloudflare
```

将以下内容添加到你的 astro.config.mjs 文件中：

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

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

阅读更多关于 Astro 中的 SSR（服务端渲染） (EN) 的信息。

故障排除

客户端 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:* 的导入语法。如果不支持，你可能需要找到一个替代的包。

More Deployment Guides

Contribute

Community