Question

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

本指南包含：

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

前提条件

开始之前，你需要：

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

如何使用 Git 部署一个站点

1. 在 Cloudflare Pages 设置一个新项目。

2. 将你的代码提交到一个 Git 仓库中 (GitHub, GitLab)。

3. 登陆 Cloudflare Dashboard 并在 Account Home > Pages 选择你的账号。

4. 选择 Create a new Project（创建一个新项目）和 Connect Git（连接 Git）选项。

5. 选择你想部署的 Git 项目并点击 Begin setup（初始设置）。

6. 使用以下的构建设置：

   • Framework preset（框架预设）: Astro
   • Build command（构建命令）: npm run build
   • Build output directory（构建输出目录）: dist

7. 点击 Save and Deploy（保存并部署）按钮。

如何使用 Wrangler 部署一个站点

1. 安装 Wrangler CLI。

2. 使用 wrangler login 在 Wrangler 登陆 Cloudflare 账号并授权。

3. 运行你的构建命令（比如 npm run build）。

4. 使用 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 了：

package.json

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

如何部署 SSR 站点

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

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

快速安装

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

npx astro add cloudflare

手动安装

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

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

   npm install @astrojs/cloudflare

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

   astro.config.mjs

   import { defineConfig } from 'astro/config';import cloudflare from '@astrojs/cloudflare';
   
   
   export default defineConfig({  output: 'server',  adapter: cloudflare()
   });

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

故障排除

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

更多部署指南

• 

  Netlify

• 

  Vercel

• 

  Deno Deploy

• 

  GitHub Pages

• 

  GitLab Pages

• 

  Cloudflare Pages

• 

  AWS

• 

  AWS via Flightcontrol

• 

  AWS via SST

• 

  Google Cloud

• 

  Firebase Hosting

• 

  Heroku

• 

  Microsoft Azure

• 

  Buddy

• 

  Edgio

• 

  Fly.io

• 

  Render

• 

  Stormkit

• 

  Surge

• 

  Cleavr

• 

  Kinsta

• 

  Deta Space

• 

  Zeabur

• 

  Zerops

Recipes