Cloudflare Pages部署静态博客完整指南：5个主流框架配置不再踩坑

凌晨两点，你终于写完了博客的第一篇文章，满怀期待地点击”部署”按钮。等了三分钟，Cloudflare Pages 显示”部署成功”，你兴奋地复制链接到浏览器，结果…页面空白，F12 打开控制台一看，全是 404。 说实话，我第一次部署 Astro 博客时也经历过这种崩溃感。当时我打开 Google 搜索”Cloudflare Pages 部署失败”，发现答案五花八门：有人说是构建命令的问题，有人说是输出目录填错了，还有人说要改配置文件。我试了三四个小时，换了好几个配置，都不行。最后发现，其实就是一个简单的配置填错了：输出目录写成了 public，而 Astro 的默认输出目录是 dist。 后来我又帮朋友部署 Hugo、Hexo 等不同框架的博客，才发现 90% 的部署失败都是因为两个配置没搞清楚：构建命令和输出目录。每个框架的默认设置都不一样，如果照着别人的教程盲目复制，很可能就掉坑里。 这篇文章会告诉你 Astro、Hugo、Hexo、Gatsby、Eleventy 这 5 个主流静态博客框架在 Cloudflare Pages 上的准确配置，还会教你遇到”页面空白”、“构建失败”等问题时怎么快速排查。照着做，10 分钟从 Git 仓库到上线。

为什么选择 Cloudflare Pages？（但要注意 2025 年的平台变化）

先说说为啥我推荐用 Cloudflare Pages 部署静态博客。 免费，而且真的快。 Cloudflare 在全球有 300 多个数据中心，你的博客会自动分发到这些节点上，无论读者在哪里访问都很快。我之前用过 GitHub Pages 和 Vercel，Cloudflare Pages 的速度确实更稳定，尤其是国内访问。而且完全免费，没有流量限制，也没有构建次数限制。 从 Git 自动部署特别省心。 你只需要连接 GitHub 或 GitLab 仓库，之后每次 git push，Cloudflare 都会自动帮你构建和部署。还能给每个 Pull Request 生成预览链接，方便你在合并前检查效果。这点对团队协作特别有用。 自带免费 SSL 证书和自定义域名。 不用折腾证书配置，绑定自己的域名也很简单，DNS 解析几分钟就生效。 不过，有个事情我得提前告诉你：Cloudflare 在 2025 年 4 月调整了平台策略，官方开始主推 Cloudflare Workers，Pages 平台基本进入”维护模式”，不会有大的功能更新了。 话说回来，对于咱们部署静态博客来说，这个变化其实影响不大。Pages 仍然稳定可用，功能也完全够用。如果你只是想搭个博客或文档站点，不需要什么复杂的服务端渲染或边缘计算，Pages 仍然是最佳选择。Workers 更适合那些需要动态功能、API 路由或者高级边缘计算的项目。 总的来说，如果你现在要部署纯静态博客，放心用 Pages。如果将来需要加服务端功能，再考虑迁移到 Workers 也不迟。

5 个主流框架的标准配置（核心章节）

好了，重点来了。这是我整理的 5 个主流静态博客框架的准确配置，直接照着填就行。

快速配置表

Astro 配置

Astro 是我现在最喜欢用的静态博客框架，性能好，写起来也舒服。 标准配置：

• 构建命令：npm run build 或者直接 astro build
• 输出目录：dist 如果你用的是纯静态站点（SSG），直接用默认配置就行。但有个坑：如果你想用服务端渲染（SSR），需要先安装 @astrojs/cloudflare 适配器，然后在 astro.config.mjs 里加上：

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

还有一点，如果你想自定义输出目录（比如改成 build），可以在配置文件里设置：

export default {
  outDir: 'build'
};

不过我建议别改，用默认的 dist 就行，省得以后协作时别人看着懵。

Hugo 配置（最容易出错）

Hugo 的坑是最多的，我当时第一次部署 Hugo 博客时，愣是折腾了一晚上才搞明白。 标准配置：

• 构建命令：hugo 或 hugo -b $CF_PAGES_URL
• 输出目录：public
• 环境变量（必须设置）：HUGO_VERSION = 0.143.1（或你需要的版本） 重点来了：Cloudflare Pages 默认用的 Hugo 版本是 0.54，这是 2019 年的旧版本！ 现在绝大多数 Hugo 主题都要求 0.80 以上，甚至 0.120+。如果你不手动设置 HUGO_VERSION，部署肯定会失败。 怎么设置环境变量？等会儿”实战流程”那部分我会详细讲，这里先记住：在 Cloudflare Pages 的项目设置里，进入 Settings > Environment variables，添加一个变量：
• 变量名：HUGO_VERSION
• 值：0.143.1（必须是精确版本号，比如 0.143.1，不能写 0.143） 还有个小细节：Hugo 的 baseURL 配置。如果你用的是 Cloudflare 提供的 .pages.dev 域名（而不是自己的域名），构建命令应该写成：

hugo -b $CF_PAGES_URL

$CF_PAGES_URL 是 Cloudflare 自动提供的环境变量，会根据部署环境自动设置正确的域名。这样你的内部链接、RSS、sitemap 等都能正常工作。

Hexo 配置

Hexo 是老牌静态博客框架了,配置相对简单。 标准配置：

• 构建命令：hexo generate（简写 hexo g 也行）
• 输出目录：public Hexo 基本不会有大问题，但某些主题或插件对 Node.js 版本有要求。如果构建失败，试试设置 NODE_VERSION 环境变量：
• 变量名：NODE_VERSION
• 值：14.3 或 18.17.0（看你项目用的版本） 你可以在本地运行 node -v 查看自己用的版本，然后在 Cloudflare Pages 里设置成一样的。

Gatsby 配置

Gatsby 是最省心的，基本不会出错。 标准配置：

• 构建命令：gatsby build
• 输出目录：public 就这么简单，没有额外配置，直接填就行。我帮朋友部署过好几个 Gatsby 博客，从来没出过问题。

Eleventy 配置

Eleventy (11ty) 是个轻量级的静态站点生成器，配置也很简单。 标准配置：

• 构建命令：npx @11ty/eleventy
• 输出目录：_site（注意是下划线开头） 有一点要注意：输出目录是 _site，前面有个下划线。别手滑写成 site，不然会找不到文件。 如果你想自定义输出目录，可以在项目根目录创建 .eleventy.js 文件，加上：

module.exports = function(eleventyConfig) {
  return {
    dir: {
      output: "public"
    }
  };
};

Next.js 配置（2025 年新变化）

如果你用 Next.js 搭博客，得注意 2025 年有个重要变化。 标准配置（2025 新方案）：

• 构建命令：npx opennextjs-cloudflare
• 输出目录：.worker-next 重要： 之前很多教程里用的 @cloudflare/next-on-pages 这个包已经废弃了，别再用了。Cloudflare 现在推荐用 @opennextjs/cloudflare 这个新适配器。 如果你看到老教程还在讲 next-on-pages，直接跳过，那已经过时了。新方案的配置步骤：

1. 安装依赖：npm install @opennextjs/cloudflare
2. 构建命令填：npx opennextjs-cloudflare
3. 输出目录填：.worker-next 不过老实说，如果你只是想搭静态博客，我不太推荐用 Next.js。它更适合需要动态功能的应用，对于纯静态内容，Astro 或 Hugo 会更轻量快速。

实战：从 Git 仓库到上线的完整流程（手把手教学）

好了，配置都知道了，现在手把手教你从零开始部署。整个流程大概 10 分钟就能搞定。

准备工作

开始之前，确认这三点：

1. 代码已经推送到 GitHub 或 GitLab - 打开你的仓库页面，确认最新代码都在上面
2. 项目有 package.json（如果是 Node.js 项目）- 确保依赖都写在里面，别本地装了但 package.json 里没有
3. 检查 .gitignore - 确认 node_modules、dist、public 等目录都在 .gitignore 里，别把构建产物推上去 我之前遇到过一个朋友，把 node_modules 也推到 Git 里了，结果部署时各种冲突。检查一下 .gitignore，省得出问题。

详细部署步骤

第 1 步：登录 Cloudflare，进入 Pages 打开 dash.cloudflare.com，登录你的账号（没有的话先注册一个，免费的）。 左侧菜单找到 Workers & Pages，点进去，然后点右上角的 Create application 按钮。 第 2 步：选择”连接到 Git” 你会看到两个选项：

• Connect to Git - 从 GitHub/GitLab 自动部署（我们选这个）
• Direct Upload - 手动上传文件（不推荐，每次都要手动传） 选 Connect to Git，然后选择 GitHub 或 GitLab。 第 3 步：授权访问 首次连接需要授权 Cloudflare 访问你的 Git 仓库。点 Sign in 按钮，会跳转到 GitHub/GitLab 的授权页面。 权限问题：如果你不想给 Cloudflare 访问所有仓库的权限，可以选择”Only select repositories”，只授权特定仓库。 授权完成后会跳回 Cloudflare 页面。 第 4 步：选择要部署的仓库 在仓库列表里找到你的博客项目，点击它。 如果没看到你的仓库，点一下右上角的刷新按钮，或者回到上一步重新授权。 第 5 步：配置构建设置（关键！） 现在是最重要的配置环节，千万别填错。
• Project name：项目名称，会成为你的 .pages.dev 域名的一部分。比如填 my-blog，域名就是 my-blog.pages.dev。
• Production branch：生产分支，一般填 main 或 master。
• Framework preset：框架预设，这里可以选你用的框架（Astro、Hugo 等），也可以选 None。 重点来了：Build settings 这里要根据你的框架填准确配置，照着前面的配置表填：
• Build command：构建命令
  • Astro: npm run build
  • Hugo: hugo 或 hugo -b $CF_PAGES_URL
  • Hexo: hexo generate
  • Gatsby: gatsby build
  • Eleventy: npx @11ty/eleventy
  • Next.js: npx opennextjs-cloudflare
• Build output directory：输出目录
  • Astro: dist
  • Hugo: public
  • Hexo: public
  • Gatsby: public
  • Eleventy: _site
  • Next.js: .worker-next 如果你选了 Framework preset，Cloudflare 会自动填入一些默认值，但不一定对，建议手动检查一遍。 第 6 步：设置环境变量（如果需要） 往下滚动，找到 Environment variables (advanced)，点 Add variable。 根据你的框架添加必要的环境变量：
• Hugo 项目必须添加：
  • Variable name: HUGO_VERSION
  • Value: 0.143.1（或你需要的版本，必须精确到三位）
• Hexo 项目（如果需要）：
  • Variable name: NODE_VERSION
  • Value: 14.3 或 18.17.0（根据你本地的版本） 环境变量填完后，配置就完成了。 第 7 步：保存并部署 检查一遍配置，确认无误后，点击页面底部的 Save and Deploy 按钮。 Cloudflare 会开始构建你的项目，你会看到一个构建日志的页面，显示实时进度。一般 1-3 分钟就能构建完成。 第 8 步：查看部署结果 构建成功后，页面会显示”Success! Your site is live!”字样，下面有一个链接，格式是 你的项目名.pages.dev。 点击链接，如果一切正常，你就能看到你的博客了！

环境变量设置详细说明

刚才在部署时可以直接设置环境变量，但如果你当时没设置，或者需要修改，可以这样做：

1. 进入你的 Cloudflare Pages 项目
2. 点击顶部的 Settings 标签
3. 左侧菜单选择 Environment variables
4. 点击 Add variable 按钮
5. 填入变量名和值，点击 Save 常用环境变量：

• HUGO_VERSION: Hugo 版本号（如 0.143.1）
• NODE_VERSION: Node.js 版本号（如 18.17.0）
• CF_PAGES_URL: Cloudflare 自动提供，不需要手动设置，用于 baseURL 重要提示：修改环境变量后，需要重新部署才能生效。进入 Deployments 标签，找到最新的部署，点右侧的三个点，选择 Retry deployment。

预览部署（Preview Deployments）

有个特别好用的功能我得提一下：每次你创建 Pull Request，Cloudflare 都会自动生成一个预览链接。 比如你在 GitHub 上创建了一个 PR 准备合并新文章，Cloudflare 会自动构建这个 PR 的代码，并生成一个独立的预览地址。你可以先看看效果，确认没问题再合并到主分支。 这对团队协作特别有用，多人写博客时可以互相审核内容。

遇到问题怎么办？常见错误和排查思路

部署过程中难免会遇到问题，别慌。这里我总结了三个最常见的错误和排查方法，基本覆盖 95% 的情况。

问题 1：构建失败（Building Failed）

错误表现：部署卡在”Building”状态，过一会儿显示”Build failed”，页面上有个红色的错误图标。 这是我遇到最多的问题。首先，别急着重新部署，先看看错误日志。 排查步骤：

1. 查看构建日志
   • 在部署失败的页面，点击 View build log 或者 Deployment details
   • 滚动到最底部，找到红色的错误信息
   • 重点看最后几行，通常会告诉你哪里出错了
2. 检查构建命令是否正确
   • 回到 Settings > Build & deployments
   • 看看 Build command 是不是按照前面的配置表填的
   • 常见错误：把 npm run build 写成了 npm build（少了 run）
3. 检查依赖是否完整
   • 如果错误日志里有”Cannot find module”或”Command not found”
   • 说明缺少依赖，检查 package.json 里是不是有这个包
   • 可能本地装了，但忘了加到 package.json 里（用 npm install --save 安装才会自动加进去）
4. 确认框架版本
   • Hugo 项目：99% 的构建失败是因为没设置 HUGO_VERSION
     • 错误日志可能会说”Theme requires Hugo Extended version”
     • 去 Settings > Environment variables 添加 HUGO_VERSION = 0.143.1
   • Hexo 项目：可能是 Node.js 版本不匹配
     • 设置 NODE_VERSION = 18.17.0（或你本地用的版本） 真实案例：我帮一个朋友部署 Hugo 博客时，构建日志显示”Hugo version 0.54.0 does not support this theme”。检查了一下，果然是版本太旧。加了 HUGO_VERSION = 0.120.0 环境变量，重新部署，秒过。

问题 2：页面空白（最常见）

错误表现：部署成功了，但访问网站只看到空白页面。F12 打开控制台，可能有一堆 404 错误。 这个问题我遇到太多次了，90% 是因为输出目录填错了。 排查步骤：

1. 打开浏览器开发者工具（F12）
   • 切到 Console 标签，看看有没有错误
   • 切到 Network 标签，刷新页面，看哪些资源 404
   • 切到 Sources 标签，看看文件结构对不对
2. 检查输出目录配置
   • 这是最常见的原因，占 90%
   • 回到 Cloudflare Pages 的 Settings > Build & deployments
   • 检查 Build output directory 是不是填对了
   • 常见错误：
     • Astro 项目填了 public 而不是 dist
     • Hugo 项目填了 dist 而不是 public
     • Eleventy 项目填了 site 而不是 _site（缺了下划线）
3. 检查 baseURL 或 publicPath 配置
   • 如果你部署到子路径（比如 example.com/blog），可能需要配置 baseURL
   • Hugo 项目：构建命令改成 hugo -b $CF_PAGES_URL
   • Astro 项目：在 astro.config.mjs 里设置 base: '/blog'
   • Vue/React 项目：可能需要设置 publicPath: './'（相对路径）
4. 检查路由模式（SPA 应用）
   • 如果你用的是 Vue Router 或 React Router 的 history 模式
   • 刷新页面时可能会 404（因为服务器找不到对应的文件）
   • 解决方案：
     • 改用 hash 模式（URL 里会有 #）
     • 或者在项目根目录添加 _redirects 文件，内容写：

       /* /index.html 200

真实案例：上次我自己部署 Astro 博客时，页面就是空白。查了半天，发现输出目录填成了 public，改成 dist 就好了。有时候真的是这么简单的错误。

问题 3：样式或资源加载失败

错误表现：页面显示出来了，但样式全乱了，图片加载不出来，看起来就像没有 CSS 一样。 排查步骤：

1. 打开开发者工具，查看 Network 标签
   • 看看 CSS、JS、图片文件是不是 404
   • 检查这些资源的请求路径对不对
2. 检查资源引用路径
   • 相对路径 vs 绝对路径问题
   • 如果 HTML 里写的是 /assets/style.css（绝对路径），但部署到子路径，就会找不到
   • 解决方案：使用框架提供的资源处理方式
     • Astro: 用 import 导入资源
     • Hugo: 用 .RelPermalink 或 absURL
     • Hexo: 用 url_for() 辅助函数
3. 检查 CDN 配置
   • 如果你用了外部 CDN（比如 jsDelivr、cdnjs）
   • 确认 CDN 链接没有被墙
   • 可以换成国内 CDN（如 BootCDN） 真实案例：之前帮一个朋友部署 Hexo 博客，页面显示了但没有样式。查看源码发现 CSS 路径是 /css/style.css，但实际文件在 /blog/css/style.css。问题是他把博客部署到了子路径，但 Hexo 配置文件里的 url 和 root 没改。修改 _config.yml，加上 root: /blog/，重新生成就好了。

快速排查清单

遇到问题时，按这个顺序检查，基本能解决：

1. ✓ 查看构建日志，找到错误信息
2. ✓ 确认构建命令是否正确（对照配置表）
3. ✓ 确认输出目录是否正确（对照配置表）
4. ✓ 检查环境变量是否设置（Hugo 项目必须设置 HUGO_VERSION）
5. ✓ 打开浏览器 F12，查看控制台和网络请求
6. ✓ 检查 .gitignore，确认没有把构建产物推到 Git
7. ✓ 在本地运行 npm run build 或 hugo 等命令，确认本地能正常构建 如果这些都检查过了还是不行，可以到 Cloudflare 社区论坛求助，或者查看官方文档的 Troubleshooting 部分。

进阶技巧：让你的博客更专业

博客上线了，但这只是开始。这里分享几个让博客更专业的技巧，都不难实现，但能大幅提升体验。

绑定自定义域名

用 .pages.dev 域名当然可以，但自己的域名更专业。而且操作特别简单，Cloudflare 还免费提供 SSL 证书。 操作步骤：

1. 在域名注册商那里（比如 GoDaddy、阿里云、腾讯云）购买一个域名
2. 进入你的 Cloudflare Pages 项目，点击 Custom domains 标签
3. 点击 Set up a custom domain，输入你的域名（比如 blog.example.com）
4. Cloudflare 会给你一些 DNS 记录，回到域名注册商的 DNS 管理页面添加这些记录
5. 等待 DNS 解析生效（通常几分钟到几小时）
6. 解析生效后，Cloudflare 会自动配置 HTTPS 证书 小技巧：如果你的域名也在 Cloudflare 管理，DNS 解析会更快，而且可以自动配置，不需要手动添加记录。

构建优化：加快构建速度

如果你的博客文章很多，构建时间可能会很长。这里有几个优化建议：

1. 启用缓存
   • Cloudflare Pages 默认会缓存 node_modules
   • 如果构建很慢，检查是不是每次都在重新下载依赖
2. 减少不必要的依赖
   • 检查 package.json，删除用不到的包
   • 能用 CDN 加载的库（如 jQuery），就别装在项目里
3. 并行构建
   • Hugo 有 --gc 参数可以清理缓存，有时能加快构建
   • Astro 可以开启 experimental.contentCollectionCache 缓存
4. 分支策略
   • 开发时可以在 dev 分支工作，只有正式发布时才合并到 main
   • 这样不会每次提交都触发生产环境构建

性能监控和分析

想知道博客的访问情况吗？Cloudflare 提供了免费的分析工具。 查看访问数据：

1. 进入 Cloudflare Pages 项目
2. 点击 Analytics 标签
3. 可以看到：
   • 总访问量（Requests）
   • 带宽使用情况（Bandwidth）
   • 访问来源国家（Requests by country）
   • 流量趋势图 Web Vitals 性能监控：

• Cloudflare 还提供 Web Vitals 监控，可以看到页面加载速度、交互延迟等指标
• 这些数据对优化用户体验特别有用
• 如果发现某个指标不好，可以针对性优化（比如压缩图片、延迟加载等）

自动化工作流

如果你想更进一步自动化，可以结合 GitHub Actions 实现一些高级功能： 示例 1：定时发布文章

• 文章写好后设置未来的发布时间
• GitHub Actions 定时检查，到时间自动发布 示例 2：自动生成 sitemap
• 每次部署后自动提交 sitemap 到搜索引擎 示例 3：图片压缩
• 推送前自动压缩图片，减少加载时间 这些功能虽然不是必须的，但能让博客运营更省心。如果你感兴趣，可以研究一下 GitHub Actions，社区里有很多现成的模板。

结论

说了这么多，其实部署静态博客真没那么复杂。关键就是搞清楚两个配置：构建命令和输出目录。只要按照前面的配置表填对了，90% 的问题都能避免。 我把核心配置再总结一下，建议收藏这个表格：

发布于: 2025年12月1日 · 修改于: 2025年12月4日

Easton

技术开发