企业官网建设流程全解析

1. 为什么我拿到一个仓库，会先打开 .github/workflows 目录

这些年我审过不少项目，不管代码质量好坏，我养成了一个习惯：先看.github/workflows/ci.yml，而不是先看 README。原因很简单，README 写的是“我想让你以为的”，CI 配置写的是“这个项目真正怎么被构建、测试和交付的”。一份二十行的 ci.yml，比几十页设计文档更能反映团队的实际工程水准。

多数人对 CI 文件的理解停留在“复制粘贴能跑就行”。拿一个 PHP 项目的配置改改包管理器名称，再换个 Node 版本，就成了另一个项目的 CI。这种用法不是不行，但一旦出现诡异现象——明明改了代码却一直跑旧流程、PR 合并后主分支不触发、fork 来的 PR 里测试全部红色——就完全不知道从何下手了。庖丁解牛的故事讲的是“依乎天理”，也就是先搞清楚肌理骨骼再动刀。CI 配置也一样，它的每一层都有明确语义：on管什么时候执行，jobs管在哪里执行，steps管怎么执行，permissions和concurrency是多数人忽略的隐形边界。不把这些骨骼摸清，你每次排查问题都是在拿刀乱砍。

这篇文章我想按我自己的拆解顺序，把一份典型.github/workflows/ci.yml从头到尾讲透。我会把每个字段背后“为什么这样设计”也一并说清楚，并且穿插一些我真实踩过的坑。适合刚接触 GitHub Actions 的人建立完整认知，也适合写过一阵子但总被奇奇怪怪问题困扰的开发者做一次系统性复盘。

2. 开局不是 name 是 on：工作流先解决“什么时候跑”

很多人打开 ci.yml 第一眼看到name，以为这就是工作流的开头。其实name只是给人看的标签，真正决定这个工作流命运的是紧随其后的on字段。我习惯把on看作工作流唯一的“入口守卫”，它没放行，后面写得再漂亮也是一堆死代码。

2.1 on 事件背后的语义差异

name: CI run-name: CI on ${{ github.ref_name }} on: push: branches: - main paths-ignore: - 'docs/**' - '**.md' pull_request: branches: - main workflow_dispatch:

push事件里最容易被忽略的是paths-ignore。我见过一个项目，每次有人改 README 都会触发一次全量构建，三套系统、十几个 job 全部跑一遍，浪费半小时。加paths-ignore: ['**.md', 'docs/**']之后问题立刻消失。但这里有个容易反噬的细节：paths-ignore和paths不能混用（如果同时出现，GitHub 会以paths为准并忽略paths-ignore）。如果你想让“仅当代码目录变化时触发”，更稳妥的写法是用paths白名单，而不是忽略黑名单。

pull_request和push的区别，很多人只说对了一半：PR 事件触发的是“合并前的验证”，而不是“合并后的结果”。更关键的是，从 fork 仓库来的 PR 不会拿到 secrets。这是平台的安全机制，防止有人通过提交恶意 PR 偷走仓库密钥。我见过不止一个团队在 PR 流程里跑集成测试，测试需要访问内部数据库密码，结果 fork PR 一来全是红的，主仓库成员一看：哎，我这本地跑是好的啊。然后花半天调试，最后发现是 secret 根本没注入——因为触发者不是仓库内部协作者。理解了这层，你就会在设计 CI 时主动把“需要密钥的步骤”从 PR 流程里摘出去，或者用pull_request_target事件配合精细的权限控制（这是另一个高阶话题，默认别用）。

2.2 permissions 和 concurrency：容易被忽略的隐形玩家

permissions: contents: read pull-requests: write concurrency: group: ${{ github.workflow }}-${{ github.ref_name }} cancel-in-progress: true

permissions这块历史包袱很重。旧仓库的默认行为是 GITHUB_TOKEN 拥有整个仓库的写权限，这意味着工作流一旦被攻破，攻击者可以直接往你的仓库推代码。现在新建的仓库默认已经被收窄，但老仓库迁移时你最好显式声明。我自己的习惯是：工作流开头永远写permissions: contents: read，只在某个 job 需要时再放宽到pull-requests: write。权限不是越全越好，而是越少越稳。

至于concurrency，它的本质是“同一时间同一分组只保留一个运行”。最经典的痛点是：你在一个 PR 上连续 push 了三次，GitHub Actions 会老老实实把三个 run 全排队跑完。前两个提交已经过时了，跑得再久也只会得到过期结论，而且白白占用配额。加了上面那两行，新 push 会自动取消还在跑的旧 run。这里分组名github.workflow-github.ref_name的含义是“同一个工作流、同一个分支/PR 上只保留最新”。如果你做的是发布流程，发布期间可别随便加cancel-in-progress: true，否则一个手动触发的发布 run 可能刚跑到一半就被另一个 push 触发的 run 顶掉，线上版本直接停在半成品状态。

3. jobs 的编排逻辑：一个 job 到底该不该只做一件事

拿到 workflow 头部之后，接下来拆的是jobs。这段是整个文件的“骨架层”，它决定了哪些活儿可以并行、哪些必须排队、以及整体最长能跑多久。很多新手在一个 job 里串十几个 step，从安装依赖一路干到部署上线，这在小型玩具项目里没问题，但一旦涉及多平台、多版本、多阶段，就开始失控。

3.1 先理解矩阵：strategy.matrix 是并行展开的开关

jobs: test: runs-on: ${{ matrix.os }} strategy: fail-fast: false matrix: os: [ubuntu-latest, windows-latest] node-version: [18, 20] steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} cache: npm - run: npm ci - run: npm test

矩阵展开时，上面这段实际会同时产生四个独立 run：Ubuntu 上跑 Node 18、Ubuntu 上跑 Node 20、Windows 上跑 Node 18、Windows 上跑 Node 20。看到这里你就明白为什么说“一个 job 只做一件事”——矩阵本来就是把一个逻辑任务复制成多份，如果这个任务还混杂着部署动作，那四个并行的部署过程会互相踩踏。

fail-fast: false是个容易被忽视的选项。默认情况下，只要矩阵里任何一个组合挂了，其余组合会被立刻取消。这在大多数场景是省资源的，但也意味着你可能只看到一种失败就再也看不到其他操作系统上的问题。我处理跨平台项目时习惯关掉它，让所有组合跑完，一次拿到完整失败列表。

3.2 needs 和 outputs：让数据在 job 之间有序流动

如果 job 之间有依赖关系——比如测试通过后才构建产物——就需要用needs声明顺序。但很多人踩过一个坑：needs只管“顺序”，不管“数据怎么传”。Job A 构建出来的产物，Job B 默认是拿不到的，因为每个 job 运行在全新的 runner 环境里。解决办法有两种：第一种是把产物上传成 artifact，再用actions/download-artifact拉下来；第二种是用 job 的outputs传递小体积的元数据。

jobs: prepare: runs-on: ubuntu-latest outputs: version: ${{ steps.export-version.outputs.version }} steps: - id: export-version run: echo "version=v1.2.3" >> "$GITHUB_OUTPUT" build: needs: prepare runs-on: ubuntu-latest steps: - run: echo "即将构建版本 ${{ needs.prepare.outputs.version }}"

这里有个 2023 年以后的语法变化值得注意：旧教程里常见的是echo "::set-output name=version::xxx"，这个命令已经被弃用且从 runner 的较新版本中移除了。现在统一用$GITHUB_OUTPUT环境变量写入。如果你在网上看到老帖子还教你set-output，千万别照抄。

3.3 timeout-minutes：给你的 CI 上保险

timeout-minutes: 30

每个 job 我都建议显式加timeout-minutes。不设默认值是多少？GitHub 官方文档给过说明：仓库级默认是 360 分钟（6 小时），个别工作流还能更长。一个 CI 任务跑 6 小时，基本就是构建脚本里某个步骤在等待输入、或者依赖源挂掉后无限重试。我在一个老项目里见过 npm 安装卡住，runner 硬生生跑了 50 多分钟才被系统杀掉。加个 30 分钟的兜底，至少能让失败来得快一点，也方便确认“耗时是否异常”。

4. step 级别的解剖：这不是“一行命令”，而是执行单元的设计

Jobs 只是划分了边界，真正承载逻辑的是steps。这一层最考功力，因为同一个需求至少有三四种写法，而不同写法之间的差异往往是“能跑”和“跑得稳”的分水岭。

4.1 uses 和 run：两种执行模式的边界

steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npm run lint

uses拉取的是预编译或源码形式的 action，它把一段复杂的逻辑封装成可复用模块。run执行的是 runner 上的 shell 命令，默认在 Linux/macOS 上用 bash，在 Windows 上用 PowerShell。这个默认值是个大坑：你以为同一段 shell 命令在windows-latest上也能跑，结果rm -rf直接报错。解决方法是给run显式指定shell: bash，让 Windows 上也能用 bash 语法：

- run: | rm -rf dist mkdir -p dist shell: bash

但注意：如果 step 里执行的是真正的跨平台命令——比如路径拼接——bash 在 Windows 上也会遇到C:\和/的差异。跨平台 CI 里，我建议路径操作统一交给 Node 脚本或专门工具，而不是随手写 shell。

4.2 三个层级的环境变量：顺序和覆盖关系

GitHub Actions 里环境变量分三个层级：workflow 级 env、job 级 env、step 级 env。作用域从大到小，同名变量越小越优先。举个例子：

env: NODE_ENV: production jobs: build: env: NODE_ENV: test steps: - env: NODE_ENV: development run: echo $NODE_ENV # 输出 development

这种覆盖规则在问题排查时特别容易迷惑人。我调试过一个 case：工作流级设置了NODE_ENV=production，某个 step 里又单独设了NODE_ENV=test，但开发者没意识到 step 里还有个残留的development。最后代码读到的环境变量既不是 production 也不是 test，而是 development。排查半小时后才从 UI 的 step 详情页里看到那个隐藏 env。每次进入一个有多个 env 层级的 job，先用一个临时 step 把所有环境变量打出来，能省非常多时间。

4.3 缓存：不是加了就万事大吉

- uses: actions/cache@v4 with: path: ~/.npm key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }} restore-keys: | npm-${{ runner.os }}-

actions/cache的原理是：运行时用key去缓存里找匹配项，找到了就恢复，找不到就执行完整逻辑；post 阶段再把当前路径打包上传，覆盖或新增缓存。这里有个常见的伪命题：缓存步数的输出是“Cache hit”，不代表后续依赖安装就是快的。npm ci本来就会先清空node_modules再完整安装，命中 npm 缓存只是让下载的包从网络上挪到了本地磁盘。如果你发现“缓存命中了但还是很慢”，优先怀疑的不是缓存，而是npm ci之外的一些自定义脚本。

缓存 key 的设计也很有讲究。用hashFiles('package-lock.json')是常见做法，但如果你多个子项目共用同一个 lock 文件位置、实际依赖却各不相同，一个子项目改依赖会误伤另一个子项目的缓存。这时候 key 里最好加上子项目路径前缀，比如client-npm-...和server-npm-...分开。

4.4 昂贵的教训：step 里不要写“惊天动地”的调试逻辑

长期维护 CI 的人都有一个体会：能把逻辑写进 action 或脚本文件的，就别堆在一长串run里。一串超过十行的 bash 命令，一旦出错，UI 上只显示红色，你只能展开日志一行行找。我更喜欢把核心逻辑抽成一个scripts/ci/*.js或*.sh文件放进仓库，CI 里只留一行调用。这样做的好处是：本地可以复现、可以用编辑器调试、代码评审也能看到真实的脚本逻辑，而不是一段谁也读不懂的 shell 魔法。这个习惯几乎是所有 CI 维护指南里最被低估的一条。

5. 从运行日志反推配置：一份真实排错记录

很多时候你要做的不是“写 CI”，而是“救 CI”。下面分享一个我近期处理的真实 case，整个排错链条几乎覆盖了 ci.yml 里所有前面提到的知识点。

5.1 现象：改动文档，却触发了一次部署

某项目的工作流长这样：

on: push: branches: [main]

看似没问题，但有一次同事提了一个只改docs/readme.md的 PR，合入 main 之后，整个 CI 跑了整整 25 分钟，还顺带把构建产物推到了测试环境。浪费资源还是小事，真正麻烦的是部署流程被一次无关变更触发，其他人不得不确认环境到底有没有被影响。

我当时的排查步骤是：先打开那次 run 的页面，确认head branch和ref_name，再逐项核对on的过滤条件。果然，这个工作流只写了branches，完全没写路径过滤。修复方案就是在on.push里加paths-ignore，把docs/**、**.md、.vscode/**这类纯文档改动排除在外。这里最微妙的一点是：paths-ignore只在 push 和 pull_request 事件里生效，对workflow_dispatch无效。所以如果你有手动触发的需求，该跑的还是会跑。

5.2 继续深挖：为什么这个仓库会频繁出现“重复执行”

修完路径问题后，我又注意到另一个现象：有人在 PR 上连推两个 commit，GitHub Actions 就把两个 run 同时跑起来。第二个 run 跑的时候，第一个其实已经失去时效性了。这是非常典型的“并发没控制”问题。我在工作流顶部加了：

concurrency: group: ci-${{ github.ref }} cancel-in-progress: true

github.ref在 push 场景下是refs/heads/main，在 PR 场景下是refs/pull/123/merge。这意味着同一分支/同一 PR 只保留一个运行。改动上线后，再连推 commit，旧 run 会在几秒内被标为cancelled，新 run 直接顶上来。这个改动对团队的体感提升是立竿见影的——再也不用看到一长串排队中的红色叉号了。

5.3 fork 来的 PR：secrets 的“隐形空白”

另一个仓库遇到的问题更典型：外包同学用 fork 方式提交了一个 PR，CI 里跑集成测试，需要DATABASE_URL这个 secret。结果是：仓库维护者那边跑得好好的，fork PR 一来就是DATABASE_URL is not set。

这不是配置错误，而是 GitHub 的安全边界。从 fork 来的 PR 不会获得 secrets，这是设计如此。你无法让 fork PR 直接拿到仓库密钥，也不应该试图绕过这个限制。正确做法是：把需要密钥的步骤限制在pull_request_target事件里执行（并且极度谨慎，因为pull_request_target会基于目标分支的代码运行，容易成为攻击面）。对于大多数项目，更稳妥的方案是让 fork PR 只跑“无需密钥的单元测试 + 静态检查”，集成测试等合入后再跑。

这个认知很重要：很多团队一看到 fork PR 失败，第一反应是去“修 secret”，搞了一晚上也没结果。其实只要理解 CI 的信任模型，几分钟就能做出判断。

5.4 从日志里快速定位问题源的三个位置

结合多年经验，我总结了一套从日志反推 ci.yml 配置问题的路径：

第一步：先看 run 的“Summary”页，确认三个信息——Event是什么（push / pull_request / workflow_dispatch）、ref_name是什么分支、以及触发者是谁（内部成员还是外部 fork）。这三项直接决定 secrets 是否能注入、路径过滤是否生效。

第二步：点进具体失败的 job，看它运行在哪个 runner 上。如果当前 job 在矩阵里，确认这次失败的是哪个矩阵组合。有时候只是 Windows 组合挂了，Ubuntu 组合全绿，这不一定是代码问题，而是路径分隔符或 PowerShell 与 bash 的差异。

第三步：展开失败的 step，先看右上角的“准备 runner”阶段是否有问题，再看run脚本输出的最后几行。大多数 bash 脚本失败信息都藏在日志尾部，但有个例外：npm ci这类命令会在中间段打出一堆 warning，真正的 error 可能混在大量输出里。这时候用浏览器搜索“error”或“npm err”比肉眼翻日志高效得多。

6. 长期维护：让 ci.yml 不变成“年久失修的骨头”

“庖丁解牛”里还有一层意思：好刀也需要反复磨。CI 配置不是写完之后一劳永逸的。依赖版本在升级、平台行为在变化、团队成员也在换。半年不动的 ci.yml，通常已经悄悄烂掉了。

6.1 给 action 版本上锁：别让“漂移”变成事故

actions/checkout@v4这种写法用的是主版本漂移（major version latest），GitHub 会在该 action 的 v4 大版本内自动使用最新补丁。这本来是好事，但有一个隐患：如果你发现某个工作流上周还跑得好好的，这周突然挂了，而仓库代码一行没改，很可能是某个第三方 action 发了一个新补丁。排查方式也很简单：在 job 日志的开头，GitHub Actions 会打印实际执行 action 的来源和 commit SHA，对照一下上次正常运行的 SHA 就能看出差异。

如果你追求极致稳定，可以把 action 固定到完整的 40 位 commit SHA：

- uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.7

但注意这需要定期手动更新，否则 action 积累的安全补丁你就错过了。折中方案是至少锁定到 tag 的大版本，并且在运行记录里注意观察是否出现非预期变化。

6.2 分支保护规则与 job 名称的绑定关系

这是一个极其隐蔽的坑：你在仓库 Settings 里配置了分支保护，要求“ci-test”这个 job 必须通过才能合入 PR。后来重构 CI，你把 job 名称从ci-test改成了test-and-lint，分支保护规则没有同步更新。结果是什么？分支保护里引用的检查名称失效后，GitHub 不会报错，只是不再等待它。你该合并还是能合并，只是大家都以为 CI 在保护，其实早就失效了。

排查方法：打开 PR 的“Checks”页（待确认），看分支保护规则实际等待的是哪个检查名。维护 CI 时如果改了 job 名，一定要顺手去 Settings → Branches 里同步更新。

6.3 小步快跑：拆分 workflow 比写一个巨型文件更可维护

当一个 ci.yml 超过两百行时，我建议按场景拆成多个文件：ci.yml管 PR 验证、release.yml管打 tag 发布、docs.yml管文档构建。这样每个文件头部都可以有独立的on触发条件，互不干扰，排查问题时定位也更直接。

如果还有跨文件复用的部分——比如每个 workflow 都要先做一次环境检查——请把它抽成一个复合 action，放在.github/actions/preflight/action.yml里。你的主工作流会变成：

steps: - uses: ./.github/actions/preflight

本地 action 和远程 action 用法几乎一样，但它的版本完全由你的仓库控制，行为可预测，这是我喜欢它的最大理由。

最后再分享一个压箱底的小习惯

我在维护 CI 时最常用的一招是：不管多复杂的配置，先让它在本地用相同命令跑通一遍，再落到 yml 里。这不只是为了调试，更重要的是让本地、CI 和文档三者之间形成对照。很多“CI 谜之失败”，本质上都是本地环境和 runner 环境不一致造成的——缓存位置不同、Node 版本不同、系统 shell 不同。你在本地能复现一次，问题的根因就露出了一半。

另外，每次修改 ci.yml 后，请故意制造一次“失败”测试。比如临时加一个必失败的命令，确认工作流确实会红色报错、并且错误信息能被人看到。这一步看着多此一举，却能把“配置写错导致 CI 静默跳过”这种事在最早时间点暴露出来。我这些年最尴尬的几次事故，全都发生在“我以为有 CI 保护，其实它根本没在跑”的状态下。

老实说，很多问题的答案并不在文档注释里，而在你一遍遍拆解、一点点理解结构的过程中。好的 ci.yml 不是文档，是项目从头到尾的骨骼。摸清了骨头，你自然知道往哪儿下刀。