OpenNext 项目中 basePath 配置问题的分析与解决方案

问题背景

OpenNext 是一个用于部署 Next.js 应用的框架，许多开发者在使用过程中遇到了与 basePath 配置相关的问题。具体表现为：当在 next.config.js 中配置了 basePath 后，通过 Lambda 函数 URL 或 CloudFront 访问带有 basePath 的路径时返回 404 错误，而不带 basePath 的路径却能正常访问。

问题现象

开发者报告的主要症状包括：

1. 配置了 basePath 为 "/basePath" 后，访问 https://example.lambda-url.ap-southeast-1.on.aws/basePath/index 返回 404
2. 直接访问 https://example.lambda-url.ap-southeast-1.on.aws/index 却能正常路由
3. 通过 CloudFront 分发时同样出现此问题

技术分析

OpenNext 与传统的 serverless-nextjs 在处理 basePath 上有显著区别：

1. 架构设计差异：

   • OpenNext 不会在服务器函数中处理 basePath 的移除
   • 而是通过生成 open-next.output.json 文件，其中包含 behaviors 字段，供 CloudFront 行为配置使用

2. 版本影响：

   • 在 OpenNext 3.0.2 版本中 basePath 功能正常工作
   • 3.0.6 及更高版本（如 3.0.8）出现了此问题
   • 问题可能与某个特定提交有关，该提交修改了路径处理逻辑

3. 正确的工作流程：

   • OpenNext 期望通过 CloudFront 行为配置来处理 basePath
   • 开发者应参考 open-next.output.json 中的 behaviors 配置来设置 CloudFront

解决方案

对于遇到此问题的开发者，建议采取以下步骤：

1. 版本回退：

   • 暂时将 OpenNext 版本固定到 3.0.2
   • 这已被多位开发者验证可以解决问题

2. 正确配置 CloudFront：

   • 确保 CloudFront 行为配置与 open-next.output.json 中的 behaviors 字段完全匹配
   • 特别注意路径模式和源设置

3. 等待修复：

   • 关注 OpenNext 项目的更新
   • 问题已被确认与特定提交相关，未来版本可能会修复

最佳实践

1. 在部署前始终检查 open-next.output.json 文件中的配置
2. 对于生产环境，考虑固定 OpenNext 版本以避免意外升级带来的问题
3. 使用 SST ion 等工具时，确保其使用的 OpenNext 版本与你的需求兼容

总结

OpenNext 在处理 basePath 时采用了不同于传统 serverless-nextjs 的方法，这要求开发者调整部署策略。当前版本存在已知问题，通过版本回退可以解决。开发者应理解 OpenNext 的设计理念，正确配置 CloudFront 行为，并关注项目更新以获取长期解决方案。