兼容性维护

保持软件与声称支持的生态（Node 版本、OS、浏览器、依赖）工作。

为什么

你的软件不在真空中跑 — 它在 Node 版本、OS、浏览器、其他依赖旁跑，且每个都演进。发布时绿的兼容矩阵在 Node 18 EOL 时变黄，传递依赖弃你 Node 版本支持时变红。维护兼容是主动测矩阵、EOL 前升、文档化支持范围的过程。无它则用户在安装时（"Node 14 不工作"）或更糟生产运行时发现不兼容。维护的兼容矩阵也是销售工具 — 企业用户采用前查，跨 5 Node 版本 + 3 OS 的绿矩阵是信任信号。

何时使用

持续 — CI 中测矩阵。依赖或运行时发新大版本或 EOL 时 revisit。

如何做

1. 定兼容矩阵：Node 版本 x OS x 浏览器（库）x 关键依赖
2. 设矩阵 CI 作业（GitHub Actions matrix）在每支持组合跑测试
3. 运行时 EOL 时（如 Node 16）：从矩阵删、升 engines 字段、公告
4. 运行时加新版本时（如 Node 22）：加矩阵为"实验"，绿时提升
5. 依赖弃你 Node 范围支持时：升你 Node 范围或钉依赖
6. 在 SUPPORTED.md 表和 package.json engines 文档化矩阵
7. 测边缘：最老支持 Node + 最老 OS + 最老依赖 — 地板组合

示例

# .github/workflows/matrix.yml — 兼容矩阵
strategy:
  matrix:
    node: [18, 20, 22]      # 支持 Node 版本
    os: [ubuntu-latest, macos-latest, windows-latest]
    exclude:
      - node: 22            # 实验，非所有 OS 绿
        os: windows-latest
steps:
  - uses: actions/setup-node@v4
    with: { node-version: ${{ matrix.node }} }
  - run: npm ci && npm test

# package.json engines（文档化契约）
"engines": { "node": ">=18.0.0 <23.0.0" }

# SUPPORTED.md
| Node | Ubuntu | macOS | Windows | 状态   |
|------|--------|-------|---------|--------|
| 18   | 绿     | 绿    | 绿      | LTS    |
| 20   | 绿     | 绿    | 绿      | LTS    |
| 22   | 绿     | 绿    | n/a     | 当前   |
| 16   | EOL    | EOL   | EOL     | 删     |

# Node 16 EOL 时（从矩阵删）
# - 从 matrix.node 删 16
# - engines 升到 ">=18.0.0"
# - changelog："BREAKING：删 Node 16 支持（EOL）。最低 Node 18。"

常见问题

⚠仅最新 Node + Linux 测 — Windows 和 macOS 用户遇 CI 从未抓的路径/编码 bug。
⚠无 engines 字段 — 用户在 Node 14 装得神秘运行时错误而非安装时清晰"不支持"。
⚠为"好"留 EOL 版本在矩阵 — CI 多跑 50% 为无人该用版本，且修复因 Node 14 失败被阻。

最佳实践

✓每支持 Node x OS 组合跑矩阵 CI — 矩阵是唯一诚实兼容契约。
✓package.json 设 engines 使不支持 Node 安装时清晰失败非运行时神秘错误。
✓及时从矩阵删 EOL 版本并公告 — 支持它们浪费 CI 且阻支持版本的修复。