基于 GitHub Actions 的 Next.js 全自动部署指南

背景

最近有次项目部署，提交完代码坐等自动部署生效，老一会了，浏览器访问一直没有更新？！😮

啥情况？原来自动部署不带编译?!?! 项目也是一段时间没更新了，忘了这个点了。😡

为了防止下次再次忘记，这次直接改成 自动编译 + 自动部署 ，又想起这次是因为改了版本号就需要发一次版本，有点麻烦，顺道也加上自动更新版本号。那就 自动编译 + 自动部署 + 自动更新版本号。

这里分享一下我们的工作流配置和流程，聊聊各个步骤怎么搞定，帮你快速上手自动部署。

配置文件地址在这里：github.com/infinilabs/...

1. 整体流程

这个工作流主要分为两个阶段：

构建阶段：在 Ubuntu 环境下拉取代码，自动检测包管理工具，安装依赖、构建 Next.js 项目，并生成静态文件。同时，新增了更新版本信息的步骤，确保站点数据始终反映最新版本。
部署阶段：将构建好的静态文件上传为 artifact，然后通过 GitHub Actions 自动发布到 GitHub Pages。

整个流程实现了全自动构建和部署，代码一更新，网站就能即时刷新上线。

2. 触发条件与权限设置

触发条件

配置文件中定义了两种触发方式：

Push 事件 ：当代码推送到 main 分支时自动运行。
手动触发 ：通过 GitHub Actions 页面可手动启动部署流程（workflow_dispatch）。

这种设置既能保证日常提交后自动部署，也能在特殊情况下手动触发流程，方便调试和应急处理。

权限配置

yaml 复制代码

permissions:
  contents: read
  pages: write
  id-token: write

这里为 GITHUB_TOKEN 分配了最小权限，确保工作流在拉取代码、发布 Pages 以及进行身份验证时都具备必要的权限。

3. 并发控制

使用 concurrency 配置避免重复部署：

vbnet 复制代码

concurrency:
  group: "pages"
  cancel-in-progress: false

这样设置可以确保同一时间只会有一个部署任务在运行，防止队列中重复部署任务互相干扰，保障生产环境的稳定性。

4. 构建阶段

4.1 Checkout 与包管理检测

Checkout ：利用 actions/checkout@v4 动作将仓库代码克隆到运行环境。
Detect package manager ：这一步通过检查项目根目录下是否存在 yarn.lock 或 package.json 来确定使用的是 Yarn 还是 NPM，并输出对应的命令和 runner 参数。这种自动化检测提高了工作流的通用性，适用于不同的包管理环境。

4.2 Node 环境与缓存配置

Setup Node ：使用 actions/setup-node@v4 配置指定版本的 Node.js，并根据包管理工具启用缓存，提高依赖安装效率。
Restore cache ：利用 actions/cache@v4 缓存 .next/cache 目录，结合锁文件和源码哈希作为缓存 key，确保在源代码或依赖发生变化时能自动更新缓存，同时加快构建速度。

4.3 更新版本信息

新增了一个步骤 Update data.json with latest version，具体操作如下：

获取版本数据 ：使用 curl 从 https://release.infinilabs.com/.latest 拉取最新的版本信息（返回 JSON 格式）。
提取版本号 ：通过 jq 分别提取 "coco-app" 和 "coco-server" 的版本号，并存入变量 APP_VERSION 和 SERVER_VERSION。
校验版本格式 ：用正则表达式检查版本号是否符合 数字.数字.数字-数字 格式。如果不符合则报错并退出，防止写入无效数据。
更新 data.json ：利用 jq 将提取到的版本号写入到 public/data.json 中的 .app 和 .server 字段。先写入临时文件，再替换原文件，确保操作的原子性。

这一环节确保了在每次构建时，站点数据文件 data.json 都能自动更新为最新的版本信息，方便前端展示或调试使用。

4.4 安装依赖与构建

Install dependencies：依据前面检测到的包管理工具自动执行安装命令。
Build with Web ：运行 next build 命令完成项目构建。这里用到了之前配置的 runner 参数，确保命令执行符合当前包管理工具的规范。

4.5 部署前的准备工作

在生成静态文件目录 ./out 下执行两个额外操作：

添加 CNAME 文件 ：通过命令 echo "coco.rs" > ./out/CNAME 为自定义域名做准备。这样 GitHub Pages 能够正确解析你的自定义域名（coco.rs）。
禁用 Jekyll ：创建一个 .nojekyll 文件，告诉 GitHub Pages 不要对静态文件进行 Jekyll 处理，从而避免文件解析错误。

最后，通过 actions/upload-pages-artifact@v3 将构建好的静态文件作为 artifact 上传，为部署阶段做准备。

5. 部署阶段

部署阶段设置了一个名为 deploy 的 job，并指定其依赖于构建阶段（needs: build），确保构建成功后才进行部署。主要步骤如下：

Deploy to GitHub Pages ：使用 actions/deploy-pages@v4 动作将之前上传的 artifact 部署到 GitHub Pages。部署成功后，工作流会输出页面 URL，并关联到 github-pages 环境。

这种分离构建与部署的方式，不仅保证了流程的清晰，也方便在出错时单独调试某一阶段。

6. 小结

用 GitHub Actions 自动化部署 Next.js 到 GitHub Pages，不仅省去了繁琐的手动操作，还实现了持续集成与持续部署（CI/CD）。这份工作流配置展示了如何：

自动检测项目使用的包管理工具。
配置 Node.js 环境和缓存机制，提高构建效率。
更新版本信息，确保 public/data.json 始终反映最新状态。
生成静态导出文件，并通过 CNAME 和 .nojekyll 做个性化配置。
利用 GitHub Actions 自动部署生成的静态文件到 GitHub Pages 上。

对于那些只需要静态内容，不依赖后端服务的 Next.js 项目来说，这种方式低成本又高效率，一旦代码更新，网站就能自动刷新上线。希望这份更新后的文档能帮你更好地理解和应用整个自动部署流程！

开源

最近，我正在基于 Tauri 开发一款项目，名为 Coco。目前已开源 ，项目仍在不断完善中，欢迎大家前往支持并为项目点亮免费的 star 🌟！

作为个人的第一个 Tauri 项目，开发过程中也是边探索边学习。希望能与志同道合的朋友一起交流经验、共同成长！

代码中如有问题或不足之处，期待小伙伴们的宝贵建议和指导！

官网: coco.rs/
前端仓库: github.com/infinilabs/...
服务端仓库: github.com/infinilabs/...

非常感谢您的支持与关注！