AWS Amplify JS 与 Next.js 14 集成时的编译问题解析

问题背景

在使用 AWS Amplify JS 与 Next.js 14 集成开发时，开发者可能会遇到一个特定的编译错误。当项目升级到 @aws-amplify/adapter-nextjs 1.1.5 或更高版本时，构建过程中会出现模块导出错误，提示 parseAmplifyConfig 未从 @aws-amplify/core/internals/utils 导出。

错误表现

构建过程中控制台会显示以下关键错误信息：

Failed to compile.
./node_modules/@aws-amplify/adapter-nextjs/dist/esm/api/createServerRunnerForAPI.mjs
Attempted import error: 'parseAmplifyConfig' is not exported from '@aws-amplify/core/internals/utils'

根本原因

这个问题通常是由于 Amplify 相关包版本不兼容导致的。具体来说：

1. @aws-amplify/adapter-nextjs 1.1.5+ 版本需要与特定版本的 aws-amplify 核心包配合使用
2. 当版本不匹配时，会导致模块解析失败
3. 使用 Bun 作为包管理器时，其缓存机制可能会加剧这个问题

解决方案

标准解决方案

1. 确保同时升级 aws-amplify 和 @aws-amplify/adapter-nextjs 到最新兼容版本：

   {
     "dependencies": {
       "@aws-amplify/adapter-nextjs": "^1.2.5",
       "aws-amplify": "^6.3.7"
     }
   }
   

2. 执行以下清理和重建步骤：

   • 删除 node_modules 目录
   • 删除 .next 构建缓存目录
   • 重新安装依赖
   • 重新构建项目

使用 Bun 时的额外步骤

如果使用 Bun 作为包管理器，还需要：

1. 删除 bun.lockb 锁文件
2. 清理 Bun 的缓存
3. 重新执行安装和构建

验证依赖关系

成功解决后，项目应包含以下关键依赖版本：

• @aws-amplify/adapter-nextjs@1.2.5
• aws-amplify@6.3.7
• @aws-amplify/core@6.3.2
• @aws-amplify/data-schema@1.3.2
• @aws-amplify/data-schema-types@1.0.1

最佳实践建议

1. 版本一致性：始终确保 Amplify 相关包的版本保持同步更新
2. 构建环境清理：在遇到类似问题时，优先清理构建缓存和依赖目录
3. 包管理器选择：如果使用非标准包管理器(如Bun)，注意其特有的缓存机制
4. 依赖检查：定期使用 npm ls 或对应包管理器的依赖树检查命令验证依赖关系

总结

AWS Amplify JS 与 Next.js 的集成通常非常顺畅，但在特定版本组合下可能会出现模块解析问题。通过保持依赖版本的一致性和彻底的环境清理，开发者可以有效地解决这类编译错误。对于使用非标准工具链的项目，需要额外注意工具特有的行为模式。