跳转到内容

部署你的 Astro 站点至 Cloudflare Pages

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

本指南包含:

开始之前,你需要:

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

如何使用 Git 部署一个站点

段落标题 如何使用 Git 部署一个站点
  1. 在 Cloudflare Pages 设置一个新项目。

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

  3. 登录 Cloudflare Dashboard 并在 Account Home > Workers & Pages > Overview 选择你的账号。

  4. 选择 Create application,然后选择 Pages 标签页,接着选择 Connect to Git 选项。

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

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

    • Framework preset(框架预设): Astro
    • Build command(构建命令): npm run build
    • Build output directory(构建输出目录): dist
  7. 点击 Save and Deploy(保存并部署)按钮。

如何使用 Wrangler 部署一个站点

段落标题 如何使用 Wrangler 部署一个站点
  1. 安装 Wrangler CLI

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

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

  4. 使用 npx wrangler pages deploy dist 进行部署。

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

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

使用 Wrangler 在本地启用预览

段落标题 使用 Wrangler 在本地启用预览

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

Terminal window
pnpm add wrangler --save-dev

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

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

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

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

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

Terminal window
npx astro add cloudflare

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

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

    Terminal window
    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(服务端渲染) 的信息。

由于 Cloudflare 的 Auto Minify(自动压缩)功能,客户端 Hydration 可能会失败。如果你在控制台中看到 Hydration completed but contains mismatches,请确保在 Cloudflare 设置中禁用 Auto Minify。

如果你正在构建一个使用 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:* 的导入语法。如果不支持,你可能需要找到一个替代的包。

更多部署指南