基于 Cloudflare Pages 与 CI/CD 自动化构建部署实战 - Hexo 博客建站与优化实战 01

发表于 分类于 阅读时长 ≈ 2 分钟
记录如何将基于 React、Vite 与 OpenCV.js (WebAssembly) 构建的前端计算密集型应用，以零服务器成本自动化部署至 Cloudflare Pages 全球 CDN。深度复盘 GitHub Actions 持续集成流水线、Node 构建版本控制以及个人自定义域名与 SSL 自动化配置细节。

1. 业务场景与核心需求

本次部署的核心目标是将一个包含密集型前端计算（涵盖复杂矩阵运算与 OpenCV.js 图像透视纠正）的纯静态 Web 应用程序，高效且低成本地部署到云端。

运行环境：

  • 核心框架：React + TypeScript + Vite
  • 图像与计算：OpenCV.js (WebAssembly) + 前端本地算法
  • 代码托管：GitHub (Algieba-dean)

核心需求：

  1. 零服务器运维：由于业务计算过程完全在客户端浏览器本地运行，无需依赖后端 Node.js 环境，需寻找纯静态的高效托管方案。
  2. 自动化 CI/CD：与 GitHub Actions 生态打通，实现代码 Push 到主分支后的自动构建与发布。
  3. 大体积静态资产加速：项目依赖较大的 .wasm 静态文件，需要借助全球 CDN 提升首次加载速度。
  4. 自定义域名与 HTTPS：需绑定托管于 Cloudflare 的个人域名，并自动完成 SSL 证书的签发。

2. 初始选型与架构决策

对于前端项目的云端部署，最初的备选方案包括 GitHub Pages 和 Cloudflare Pages。

虽然 GitHub Pages 是常规选择，且项目本身已经配置了针对核心逻辑的 CI 测试流程，但在全球网络访问的连通率、构建缓存速度以及自定义域名的集成深度上，Cloudflare Pages 具有显著优势。

特别是在 DNS 管理层面，由于主域名已经托管在 Cloudflare，使用 Pages 可以实现免配置的 CNAME 记录自动挂载和边缘证书颁发。此外，Cloudflare 的骨干网缓存对于 WebAssembly 文件的分发有着极好的加速效果。

3. 部署过程中的技术关键点

在实际将 Vite 项目接入 Cloudflare Pages 时，主要面临以下配置细节，若忽略可能导致构建失败或线上运行异常：

关键点：构建环境 Node.js 版本漂移
Vite 的较新版本在底层严重依赖现代 Node.js 的特性，通常硬性要求 Node.js 18 或更高版本。如果在 Cloudflare 构建平台上不显式声明版本，其底层构建容器可能默认拉取旧版 Node 镜像，导致 npm run build 阶段直接抛出语法错误或依赖安装失败。必须通过环境变量将构建运行时强制锁定在稳定的 LTS 版本（如 Node 20）。

4. 最终自动化部署落地路径

整个部署链路在 Cloudflare 控制面板的“Workers 和 Pages”模块中完成，具体步骤如下：

步骤一：授权与代码库绑定

  1. 进入 Cloudflare 控制台，导航至 构建 -> 计算下的 Workers 和 Pages。
  2. 点击 创建应用程序，选择页面底部的 想要部署 Pages？点击开始使用。
  3. 选择 导入现有 Git 储存库，授权后在列表中选中目标仓库，点击 开始设置。

步骤二：配置 Vite 构建参数与环境变量

在项目设置页面，针对 React + Vite 框架特性填写对应的构建指令，并在环境变量模块注入环境锁定参数：

  • 框架预设 (Framework preset): 选择 Vite (或无框架预设时手动填入以下两项)。
  • 构建命令 (Build command): npm run build
  • 构建输出目录 (Build output directory): dist

展开底部的 环境变量 (Environment variables) 设置，添加 Node.js 版本控制：

1
2
变量名称: NODE_VERSION
值: 20

保存并部署后，Cloudflare 会自动分配构建容器，拉取代码执行 npm install 与构建命令，最后输出一个 xxx.pages.dev 的默认访问地址。

步骤三：绑定自定义域名并激活

项目上线后，进入页面的 自定义域 选项卡：

  1. 填入准备好的新二级域名。
  2. 点击 激活域。
  3. 此时无需手动干预 DNS 解析，Cloudflare 自动在后台添加一条指向 Pages 默认域名的 CNAME 记录，并开启“已代理”状态，同时申请边缘 TLS 证书。

5. 总结与实践建议

  1. 环境锁定是最佳实践：不仅是 NODE_VERSION，在任何依赖 Node 环境的 CI/CD 流程中，显式声明运行版本都能有效防御因云厂商底层镜像升级带来的“破窗效应”。
  2. 纯前端重计算应用的红利：通过将复杂的数学矩阵运算与图像处理下放到浏览器端解决（利用 WebAssembly 和本地算力），我们彻底免去了后端服务器的计算及内存开销，配合 Cloudflare Pages 实现了真正的零成本、高性能云端部署。
  3. CI 测试的补充：目前依靠 GitHub Actions 运行的单元测试与 Cloudflare Pages 的构建发布是解耦的。为了保证线上质量，建议在 GitHub 仓库设置分支保护规则，只有当测试用例在 CI 中完全通过后，才允许合并代码触发 Pages 部署。