Lesson 0008 CI 集成：用 GitHub Actions 自动运行测试

Lesson 0007 给了你自动化验证——npm test 3 秒出结果。但这里有一个 gap：测试只在你记得跑的时候才有用。本课补上缺失的另一半：让测试在每次 push 和 PR 时自动运行。你会学会编写 GitHub Actions workflow 文件，理解 CI 是如何成为"编码 → 发布"流水线中的安全守门人。

1. 为什么 CI——从手动验证到自动守门

Lesson 0007 教你写了 8 个 fixture + 8 个测试用例。你每次改代码后可以跑 npm test，3 秒确认没弄坏什么。但这里有一个关键问题：

三者互补，不是替代——它们分别守在不同位置：

• 手动 npm test：开发中 3 秒快速反馈
• pre-push hook：push 前自动跑——但 --no-verify 可绕过，它是便利工具而非安全机制
• CI：服务端强制执行——clean room 环境，结果全团队可见，配合分支保护规则物理阻止合并

你完全可以三者都用：pre-push hook 快速拦截低级错误，CI 在云端做最终裁决。但 pre-push hook 的"不通过就不 push"有一个根本局限：它是客户端脚本——团队里任何一个人 git push --no-verify 就跳过了。真正不可绕過的守门人，是服务端的 CI + 分支保护规则。

2. GitHub Actions 概览

GitHub Actions 是 GitHub 内置的 CI/CD 服务。它的核心概念用一张表就能说清：

2.1 触发器详解

on 决定了 workflow 什么时候启动。最常用的四种：

2.2 为什么选 GitHub Actions 而不是其他

其他 CI 工具（Jenkins、Travis CI、CircleCI）也能做同样的事。但 GitHub Actions 有两个不可替代的优势：

1. 零配置集成。 不需要单独注册账号、不需要配置 webhook、不需要管理密钥轮换——workflow 文件和代码放在同一个仓库里，GitHub 自动发现并执行
2. 公开仓库免费。 一个 VS Code 扩展的 CI 需求（每月几百次运行）完全在免费额度内

对于一个独立开发者的 VS Code 扩展项目，外部 CI 工具的额外复杂度不带来任何收益。

3. 测试工作流详解——逐行拆解

以下是一个最简可用的测试 workflow。把它放在 .github/workflows/test.yml，GitHub 就会自动执行：

# ===== .github/workflows/test.yml =====
name: Test                          ← 在 Actions 页面显示的名称

on:                                    ← 触发器
  push:
    branches: [main]                  ← 向 main 推送时触发
  pull_request:
    branches: [main]                  ← 向 main 发起/更新 PR 时触发

jobs:                                  ← 作业列表
  test:                               ← 作业 ID（自定义名称）
    runs-on: ubuntu-latest            ← 运行器操作系统
    steps:                            ← 步骤列表（顺序执行）
      - uses: actions/checkout@v4   ← 步骤 1：克隆仓库代码

      - name: Setup Node.js
        uses: actions/setup-node@v4 ← 步骤 2：安装 Node.js
        with:
          node-version: '20'          ← 指定 Node 版本

      - name: Install dependencies
        run: npm ci                  ← 步骤 3：安装依赖

      - name: Run tests
        run: npm test               ← 步骤 4：运行测试

3.1 每个步骤在做什么

步骤 1——actions/checkout@v4：这是一段 GitHub 维护的开源代码。它的作用是把你的仓库克隆到运行器上。没有这一步，运行器的文件系统是空的——没有源代码，什么都做不了。@v4 是 Git 标签，锁定大版本以保证稳定性。

步骤 2——actions/setup-node@v4：安装指定版本的 Node.js。它还自动处理 node_modules 缓存——如果存在 package-lock.json，它会智能地跨运行复用已下载的包，加速后续运行。

步骤 3——npm ci：这是最关键的一步，也是新手最容易踩的坑。

步骤 4——npm test：这是唯一与你代码直接相关的命令。但——等等——package.json 目前还没有 test 脚本。这个 gap 正是第 6 节要解决的问题。

3.2 运行器：一台全新的虚拟机

理解一个关键事实：当 workflow 启动时，ubuntu-latest 是一台全新的虚拟机。它上面没有你的源代码、没有安装 Node.js、没有 node_modules。每一步都在从头构建环境：

Runner 初始状态：空目录
  ├─ Step 1 (checkout)    → 克隆仓库代码 ✅
  ├─ Step 2 (setup-node)  → 安装 Node.js 20 ✅
  ├─ Step 3 (npm ci)      → 安装 npm 依赖 ✅
  └─ Step 4 (npm test)    → 运行测试 ✅
每一步依赖前面步骤构建的状态

这正是 CI 的核心价值：它证明你的代码能在没有你机器上隐藏状态的前提下运行。如果你的测试在本地通过但在 CI 失败，那一定是因为你的机器上有某些"特殊条件"——全局安装的包、未提交的配置文件、环境变量——CI 帮你发现了它们。

4. CI 作为发布前的守门人

你的项目已经有一个 workflow 了——.github/workflows/publish.yml。把它和我们要创建的 test.yml 放在一起看：

把它们串起来，就是完整的 dev→publish 流水线：

开发 → 本地测试 → push 到 main
                    ↓
              CI 运行 test.yml
               ↙        ↘
          通过 ✅       失败 ❌ → 修 bug → 回到"开发"
            ↓
      打 tag v1.5.0 → 推送
                         ↓
                   CI 运行 publish.yml
                         ↓
              发布到 Marketplace + Open VSX

5. Node 版本矩阵——测试多版本

VS Code 扩展有一个特殊考量：不同版本的 VS Code 内嵌了不同版本的 Node.js。你的扩展在 package.json 中声明 "engines": {"vscode": "^1.74.0"}——这意味着它支持的 VS Code 版本跨度可能覆盖多个 Node 版本：

你的扩展用户可能运行在 Node 18、20 或 22 上。测试所有三个版本是务实的折中——Node 16 已 EOL，不值得维护；18/20/22 覆盖了绝大多数用户。

GitHub Actions 的 matrix strategy 让你用几行 YAML 同时在多个 Node 版本上运行测试：

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ['18', '20', '22']  ← 3 个值 = 3 个并行 job
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}  ← 引用矩阵变量
      - run: npm ci
      - run: npm test

6. 添加 test 脚本到 package.json

回头看 temp_repo/package.json 的 scripts 块——它缺少最关键的一行：

"scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./",
    "lint": "eslint src --ext ts",
    //                              ← 没有 "test" 脚本！
    "package": "vsce package",
    "publish": "vsce publish"
}

有两种方式定义 test 脚本：

6.1 pretest 钩子——自动化编译

npm 有一组内置的生命周期钩子：如果你定义了 pretest，npm 会在执行 test 之前自动运行它。利用这个机制，npm test 可以自动编译：

"scripts": {
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./",
    "lint": "eslint src --ext ts",
    "pretest": "npm run compile",     ← npm 在 test 前自动运行
    "test": "node --test out/**/*.test.js",  ← 新增
    "package": "vsce package",
    "publish": "vsce publish"
}

现在 npm test 的执行顺序是：pretest（编译 TypeScript）→ test（运行测试）。一个命令，两步自动完成。

7. 完整的 workflow 文件

把所有概念组合在一起，这是最终的 .github/workflows/test.yml：

# ===== .github/workflows/test.yml =====
name: Test

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ['18', '20', '22']
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - name: Install dependencies
        run: npm ci

      - name: Compile TypeScript
        run: npm run compile

      - name: Run tests
        run: npm test

8. 练习

1. 编辑 temp_repo/package.json，在 scripts 中添加 "pretest": "npm run compile" 和 "test": "node --test out/**/*.test.js"。运行 npm test——即使没有测试文件，node --test 也应该干净退出（无匹配文件不算失败）。确认 pretest → test 的执行顺序
2. 在 temp_repo/.github/workflows/ 目录下创建 test.yml，使用第 3 节的最简版本（单 Node 版本，无矩阵）。逐行检查 YAML 缩进——必须是 2 个空格，不能是 tab。不要把 out/ 目录提交到 Git——CI 会在运行时编译
3. 修改 test.yml，加入 strategy.matrix（node-version: ['18', '20', '22']）。在修改之前先回答：这个矩阵会产生几个 job？如果加 os: [ubuntu-latest, windows-latest] 呢？
4. （思维练习）画一张决策树：以下操作分别会触发哪些 workflow？
   a) git push origin main
   b) 从 feat/foo 分支向 main 发起 PR
   c) git tag v1.6.0 && git push origin v1.6.0
   d) 向 feat/bar 分支 push（没有对应的 PR）
5. （探索）打开 github.com/ezoosk/claude-context-bar/actions——查看 publish workflow 的历史运行记录。找到一个成功运行和一个失败运行（如果有），展开步骤日志，观察每一步的耗时和输出。这是你的 test.yml 推送后会出现的同一页面
6. （延伸）在 workflow 中添加 lint 步骤：在 npm test 之前加一个 step 运行 npm run lint。思考：lint 失败应该阻止测试运行吗？还是应该并行跑？如果你不确定答案——这说明你已经触碰到了 CI 设计的核心权衡：快速失败 vs 全面反馈

9. 知识检查

10. 推荐深入阅读

• GitHub Actions：Understanding the workflow file — 官方 workflow 语法完整参考
• GitHub Actions：Using a matrix for your jobs — 矩阵策略详解（含排除项、并行限制）
• actions/checkout — checkout action 源码和文档（子模块、稀疏检出等高级选项）
• actions/setup-node — setup-node action（缓存机制、版本解析、registry 配置）
• npm-ci 官方文档 — npm ci vs npm install 的详细行为差异
• VS Code：Publishing Extensions — CI 的终点：Marketplace 发布
• Lesson 0007：单元测试 — 本课的直接前置：先有测试，再有 CI
• GitHub：About protected branches — 进阶：用分支保护规则强制 CI 通过才能合并