SST v3 迁移后 Next.js Pages Router API 失效问题解析

问题背景

在将基于 Next.js 12 构建的大型项目升级到 Next.js 14 并保持 Pages Router 架构的过程中，开发团队遇到了 API 路由失效的问题。项目原本使用 cdk-nextjs-standalone 部署到 AWS 环境运行良好，但在升级后 API 路由全部返回 404 错误。

技术栈版本

• Next.js 版本：v14.2.20
• SST 框架版本：v3.3.65
• OpenNext.js 版本：3.2.2

问题现象

开发团队在完成以下技术升级后发现问题：

1. 从 Next.js 12 升级到 14 版本
2. 保持原有的 Pages Router 架构不变
3. 从 cdk-nextjs-standalone 迁移到 SST v3 框架

尽管部署过程顺利完成，但所有 API 路由均无法正常工作，请求时返回 404 页面。

技术分析

这种问题通常出现在 Next.js 架构升级与部署工具变更的交叉点上。Next.js 14 虽然保留了 Pages Router 的支持，但在底层实现上有所调整。同时，从 cdk-nextjs-standalone 迁移到 SST v3 涉及部署架构的重大变化。

解决方案

经过技术团队深入排查，发现问题根源在于 OpenNext 的实现细节。解决方案需要对部署配置进行特定调整：

1. 确保 API 路由文件被正确识别和处理
2. 检查路由映射配置
3. 验证构建输出结构是否符合预期

最佳实践建议

对于类似的技术迁移场景，建议采取以下步骤：

1. 分阶段进行升级：先升级 Next.js 版本，验证功能正常后再进行部署工具迁移
2. 建立完整的测试覆盖，特别是 API 路由的测试用例
3. 仔细对比新旧部署工具的输出差异
4. 关注社区已知问题和解决方案

总结

Next.js 架构升级与部署工具变更同时进行时，需要特别注意 API 路由的兼容性问题。通过合理的迁移策略和配置调整，可以确保平稳过渡到新版本技术栈。