AWS SDK for JavaScript v3 在 Next.js 构建中的兼容性问题分析

问题背景

AWS SDK for JavaScript v3 是目前 AWS 官方推荐的 JavaScript SDK 版本。近期有开发者反馈，在使用 Next.js 框架构建项目时，当引入 @aws-sdk/client-s3 和 @aws-sdk/s3-request-presigner 这两个包且版本高于 3.623.0 时，会出现构建错误。

错误现象

具体错误信息表现为：

Cannot get final name for export 'NO_RETRY_INCREMENT' of ../node_modules/.pnpm/@smithy+util-retry@3.0.3/node_modules/@smithy/util-retry/dist-es/index.js

这个错误在版本 3.624.0 及以上出现，而 3.623.0 及以下版本则能正常构建。

技术分析

根本原因

该问题源于 Next.js 的构建系统与 AWS SDK v3 中某些模块的导出方式不兼容。具体来说：

1. AWS SDK v3 从 3.624.0 版本开始，内部依赖的 @smithy/util-retry 模块的导出方式发生了变化
2. Next.js 的构建工具在处理这些模块导出时出现了识别问题
3. 这个问题特别影响使用 pnpm 作为包管理器的项目

影响范围

• 仅影响 Next.js 项目构建阶段
• 仅影响 @aws-sdk/client-s3 和 @aws-sdk/s3-request-presigner 3.624.0 及以上版本
• 在 Turborepo 等 monorepo 结构中问题更为明显

解决方案

临时解决方案

1. 版本回退：暂时使用 3.623.0 版本

   {
     "@aws-sdk/client-s3": "3.623.0",
     "@aws-sdk/s3-request-presigner": "3.623.0"
   }
   

2. Next.js 配置调整：在 next.config.js 中添加以下配置

   // Next.js 14
   const nextConfig = {
     experimental: {
       serverComponentsExternalPackages: ['@aws-sdk/client-s3', '@aws-sdk/s3-request-presigner']
     }
   }
   
   // Next.js 15
   const nextConfig = {
     serverExternalPackages: ['@aws-sdk/client-s3', '@aws-sdk/s3-request-presigner']
   }
   

3. Monorepo 特殊处理：在 Turborepo 结构中，需要在 Next.js 应用的 devDependencies 中显式添加相关依赖

长期解决方案

AWS SDK 团队和 Next.js 团队需要协调解决模块导出的兼容性问题。开发者可以关注两个项目的更新日志，等待官方修复。

技术建议

1. 对于新项目，建议直接使用最新版本的 Next.js 和 AWS SDK，并按照官方文档配置
2. 在 monorepo 结构中，确保所有必要的依赖都在使用它们的应用中显式声明
3. 定期检查 AWS SDK 和 Next.js 的更新，及时升级以获得更好的兼容性和性能

总结

AWS SDK for JavaScript v3 与 Next.js 的集成在大多数情况下工作良好，但在特定版本组合下会出现构建问题。开发者可以通过版本控制或配置调整来解决当前问题，同时应关注官方更新以获取永久性解决方案。理解这些兼容性问题的本质有助于开发者更好地构建和维护基于 AWS 和 Next.js 的现代 Web 应用。