如果你在 GitHub 上托管个人站点,但还不太熟悉自动化,最稳妥的第一步不是急着配置自动部署,而是先搭一个只做“构建检查”的最小工作流。它的目标很简单:每次你推送代码或发起拉取请求时,GitHub 自动帮你跑一次站点构建,如果构建失败,就告诉你失败在哪一步。这样你既能提前发现代码问题,又不用马上接触密钥、部署令牌这些容易让人困惑的概念。
这篇文章会带你从零开始,创建一个只负责构建检查的 GitHub Actions 工作流。我们会把重点放在 workflow 文件的位置、触发条件、步骤顺序,以及如何从失败日志里定位具体问题。完成之后,你会对 GitHub Actions 的运行方式有一个直观的理解,之后再扩展部署功能也会更有把握。
准备工作:确认你的站点构建方式
在动手写工作流之前,先明确你个人站点的技术栈。不同站点框架的构建命令不一样,但这不会影响工作流的基本结构,只是中间某个步骤的命令需要替换。
假设你的站点是 Node.js 项目(比如使用 Vite、Next.js、Hugo 的 npm 版本等),那么核心构建命令通常是:
npm install
npm run build
如果你的站点是 Python 项目(比如使用 MkDocs、Pelican),那么对应的命令可能是:
pip install -r requirements.txt
mkdocs build
无论哪种情况,你都需要知道两件事:安装依赖的命令和生成静态文件的命令。如果还不确定,先在你的本地电脑上手动跑一遍,确认能成功构建,再继续下面的步骤。
创建 workflow 文件:位置与基本结构
GitHub Actions 的工作流文件是一个 YAML 格式的文本文件,它必须放在仓库的特定目录下,GitHub 才会识别。
你需要在你仓库的根目录下创建如下路径:
.github/workflows/
在这个目录里,新建一个文件,名字可以自定义,比如 build-check.yml。GitHub 会扫描这个目录下的所有 .yml 或 .yaml 文件,并自动识别为工作流。
一个最小的工作流文件长这样:
name: Build Check
on:
push:
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm install
- name: Build site
run: npm run build
这个文件虽然只有十几行,但它已经包含了工作流的核心要素。我们先逐段理解它。
理解触发条件:什么时候会运行
文件开头的 on: 字段定义了工作流的触发条件。上面例子中写的是:
on:
push:
pull_request:
这两行表示:每次有人向仓库推送代码(push),或者有人发起拉取请求(pull_request)时,这个工作流都会运行。
注意,这里没有限定分支,所以任何分支的推送都会触发。如果你只想在 main 或 master 分支上运行,可以加上分支过滤:
on:
push:
branches:
- main
pull_request:
branches:
- main
对于个人站点来说,通常建议至少在 main 分支上运行检查,因为那是你发布用的分支。但如果你还在其他分支上开发,保留所有分支的检查也问题不大,只是会消耗一些 Actions 配额。
运行环境与依赖安装:每个步骤在做什么
jobs 部分定义了工作流要执行的任务。这里我们只有一个任务,名为 build。
runs-on: ubuntu-latest 指定了运行环境。GitHub 会为每次运行启动一台全新的 Ubuntu 虚拟机,这台机器是干净的,不包含你项目的任何文件,所以第一步必须是获取你的代码。
steps 列表按顺序执行,每一步都是一个独立动作:
- Checkout code:
actions/checkout@v4是 GitHub 官方提供的动作,作用是把你的仓库代码下载到这台虚拟机上。没有这一步,后面所有操作都无从谈起。
- Setup Node.js:
actions/setup-node@v4配置 Node.js 环境。这里指定了版本'20',你也可以改成你本地使用的版本。如果你的站点是 Python 项目,这一步就换成actions/setup-python@v5,并指定python-version。
- Install dependencies:
run: npm install是直接执行的 shell 命令,安装项目依赖。这一步对应你本地构建时的依赖安装。
- Build site:
run: npm run build执行构建命令,生成静态文件。
这里有一个关键点:如果其中任何一步返回非零退出码(即命令执行失败),工作流会立即停止,后续步骤不会执行。这正是我们做构建检查的意义——构建失败时,工作流会以失败状态结束,并在日志中标记出是哪一步出了问题。
提交并验证:第一次运行
把 build-check.yml 文件保存后,提交并推送到 GitHub。你可以在仓库页面的 Actions 标签页看到这次运行。
点击进入运行详情,你会看到 build 任务,再点进去就能看到每个步骤的执行状态。每个步骤旁边会有一个图标:绿色对勾表示成功,红色叉号表示失败。
如果所有步骤都显示绿色,恭喜你,构建检查已经生效了。之后每次推送,GitHub 都会自动执行这个流程。
定位失败日志:从红叉到具体原因
当工作流失败时,第一步是点击那个红色叉号的步骤,展开它的日志。日志会显示该步骤执行的完整命令输出,失败原因通常就在最后几行。
常见的失败情况有以下几种:
依赖安装失败:Install dependencies 步骤报错。通常是因为 package.json 中指定的依赖版本不存在,或者网络原因导致下载失败。日志中会显示具体的错误信息,比如 npm ERR! 404 Not Found。
构建命令失败:Build site 步骤报错。这可能是代码中的语法错误、引用了不存在的文件,或者是构建配置有问题。日志中会显示构建工具的报错信息,比如 Vite 会提示 ERROR: [vite] Rollup failed to resolve import。
环境配置问题:Setup Node.js 或 Setup Python 步骤报错。通常是你指定的版本号不存在,或者与项目要求不兼容。比如项目需要 Node.js 18,但你指定了 '20',某些旧依赖可能不兼容。
定位失败日志的核心思路是:顺着步骤顺序往下看,找到第一个失败的步骤,然后查看该步骤日志的末尾部分。错误信息一般会明确指向具体文件或命令,根据这个线索回到本地代码中修复即可。
另外,GitHub 默认会保留工作流运行日志 90 天(从 2026 年 10 月 1 日起,检查、工作流运行和提交状态的保留策略将统一适用,但在此之前保留期更长)。所以即使你隔几天才处理,日志也还在。
常见问题与调整方向
工作流文件改了但没触发? 检查文件名后缀是否为 .yml 或 .yaml,以及文件是否在 .github/workflows/ 目录下。另外,确认你推送到了正确的分支,并且 on: 的触发条件包含该分支。
不想每次推送都跑? 可以在 on.push.branches 中限定分支,或者添加 paths 过滤,只在特定文件变更时触发。比如只关心 src/ 目录下的变化:
on:
push:
paths:
- 'src/**'
构建检查通过后想自动部署? 这是下一步的事。你需要在工作流中增加部署步骤,并配置相应的权限或令牌。建议先把构建检查稳定运行一段时间,确认每次都能正确反映代码状态,再考虑扩展。
想回退到之前的配置? 修改 workflow 文件并推送即可,GitHub 会以仓库中最新的 workflow 文件为准。如果你改坏了,查看之前的提交记录,恢复文件再推送一次就行。
构建检查工作流虽然简单,但它建立了一个自动反馈的闭环:你推送代码,GitHub 帮你验证,失败时告诉你哪里有问题。掌握这个流程后,你会对 GitHub Actions 的运行逻辑有一个清晰的认识,之后再添加部署、通知等功能,也只是在这个基础上增加步骤而已。
















































新手最容易漏掉的应该是工作流文件的目录
分支过滤和路径过滤能一起用吗?
以前总在本地能跑、推上去就报错,自动检查很有必要
日志里从第一个失败步骤开始看,确实省事
顺着步骤查省时间,遇到报错不容易乱
先做构建检查再考虑部署,这个顺序挺稳妥