Azure SDK for JS 中 @azure/identity 与 Node.js 24 的兼容性问题解析

问题背景

在 Node.js 24 发布初期，开发者在使用 @azure/identity 4.9.1 版本时遇到了一个运行时错误。这个错误表现为无法读取 undefined 的 prototype 属性，具体发生在 buffer-equal-constant-time 模块中。

技术分析

这个问题的根源在于 Node.js 24 的一个破坏性变更。Node.js 核心团队在 24.0.0 版本中移除了 Buffer 模块中的 SlowBuffer 类，而这个类被 buffer-equal-constant-time 1.0.1 版本所依赖。

错误调用栈显示：

@azure/identity → @azure/msal-node → jsonwebtoken → jws → jwa → buffer-equal-constant-time

buffer-equal-constant-time 的代码尝试访问 SlowBuffer.prototype.equal，但在 Node.js 24 中这已不再可用。

解决方案演进

1. Node.js 端的修复：Node.js 团队在 24.0.1 版本中撤销了这个破坏性变更，暂时恢复了向后兼容性。

2. 依赖链更新：上游的 jwa 包也已经更新，开发者可以通过重新生成 lock 文件来获取修复后的版本。

3. 长期解决方案：虽然当前问题已解决，但 Node.js 团队计划在 25 版本中正式移除 SlowBuffer。届时 @azure/msal-node 需要更新其依赖链，特别是 jsonwebtoken 相关的依赖。

开发者建议

1. 对于遇到此问题的开发者，建议立即升级到 Node.js 24.0.1 或更高版本。

2. 如果问题仍然存在，可以尝试以下步骤：

   • 删除 node_modules 和 lock 文件
   • 重新安装依赖
   • 确保获取到最新版本的 jwa 和 buffer-equal-constant-time

3. 为未来 Node.js 25 的变更做好准备，关注 @azure/msal-node 的更新情况。

总结

这个案例展示了现代 JavaScript 生态系统中依赖管理的复杂性。作为开发者，我们需要：

• 关注核心运行时的重要变更
• 理解依赖链的传递关系
• 及时更新依赖版本
• 为即将到来的破坏性变更做好准备

Azure SDK 团队会持续关注这类兼容性问题，并与相关依赖的维护团队协作，确保开发者体验的顺畅。