Gitbeaker CLI 在 Node.js 22 环境下的兼容性问题解析

问题背景

Gitbeaker 是一个流行的 GitLab API 客户端库，其 CLI 工具在 Node.js 22 环境下出现了兼容性问题。当用户尝试运行 gitbeaker --version 命令时，会抛出语法错误，提示 Unexpected identifier 'assert'。

技术原因分析

这个问题的根源在于 Node.js 22 移除了对 import...assert 语法的支持。在 Node.js 的早期版本中，JSON 导入通常使用 assert { type: 'json' } 语法，但这种语法在 Node.js 22 中被废弃，取而代之的是 with { type: 'json' } 语法。

解决方案探讨

语法替换方案

最直接的解决方案是将 assert 关键字替换为 with。然而，这带来了一个兼容性挑战：with 关键字只在 Node.js 18.20.0 及以上版本中支持。考虑到 Gitbeaker 的最低支持版本已经是 Node.js 18，这个方案在理论上是可行的。

构建工具的影响

在实际实施过程中，发现了一个更深层次的问题：构建工具链的选择会影响最终的语法输出。Gitbeaker CLI 使用 tsup 进行构建，当启用 tree shaking 功能时，tsup 会使用 Rollup 而非 esbuild 进行打包。而 Rollup 默认会将 import 属性转换为 assert 语法，这就导致了即使源代码中使用 with，构建后仍然会输出 assert。

最佳实践建议

1. 构建工具调整：建议将构建工具配置调整为直接使用 esbuild，因为 esbuild 默认支持 tree shaking 且能正确处理 import 属性语法。

2. 版本兼容性策略：明确声明对 Node.js 版本的要求，确保用户环境符合最低版本要求（Node.js 18.20.0+）。

3. 持续集成测试：在 CI 流程中加入对 Node.js 22 的测试，确保新版本的兼容性。

总结

这个问题展示了现代 JavaScript 生态系统中版本兼容性的复杂性。它不仅涉及语言特性在不同 Node.js 版本中的变化，还涉及到构建工具链的选择对最终产物的影响。对于库开发者而言，保持对最新 Node.js 版本的兼容性测试，并理解构建工具的底层行为，是维护项目健康的重要环节。

通过这次问题的解决过程，Gitbeaker 项目不仅修复了 Node.js 22 的兼容性问题，也为未来处理类似的语法变更积累了经验。