SST 项目中 Next.js 应用在非根目录部署问题的分析与解决

问题背景

在使用 SST (Serverless Stack) 构建 Monorepo 项目时，开发者遇到了一个典型问题：当 Next.js 应用不在项目根目录下时（例如放在 apps/nextjs 子目录中），部署后会出现应用无法正常运行的情况。具体表现为部署完成后 Next.js 开发服务器标签页冻结，或者间歇性出现 "next command not found" 的错误。

问题复现环境

• 项目结构：Monorepo 架构，Next.js 应用位于 apps/nextjs 子目录
• 技术栈：
  • SST 框架
  • Next.js 应用
  • pnpm 包管理器
• 运行环境：
  • macOS (Apple Silicon)
  • Node.js 20

问题分析

经过深入排查，发现该问题可能由多个因素共同导致：

1. 包管理器冲突：项目中混合使用了 npm 和 pnpm，这种混合使用可能导致依赖解析不一致
2. Next.js 应用命名冲突：Next.js 应用的 package.json 中 name 字段设置为 "next"，这可能与 Next.js 本身的命令产生冲突
3. 路径解析问题：使用 path.resolve 处理应用路径可能导致某些环境下路径解析异常
4. 工作区配置缺失：缺少 pnpm-workspace.yaml 文件导致 monorepo 工作区功能不完整

解决方案

1. 统一包管理器

建议在整个项目中统一使用单一包管理器（npm 或 pnpm）。如果选择 pnpm，需要：

• 删除项目中的 package-lock.json
• 添加 pnpm-workspace.yaml 配置文件：

packages:
  - "apps/*"
  - "packages/*"

• 运行 pnpm install 重新安装依赖

2. 修改 Next.js 应用命名

避免在 package.json 中使用可能产生冲突的名称（如 "next"），改为更具描述性的名称，例如：

{
  "name": "my-next-app",
  // 其他配置...
}

3. 简化路径配置

在 SST 配置中，避免使用复杂的路径解析，直接使用相对路径：

new sst.aws.Nextjs("MyWeb", {
  path: "apps/next",
  link: [bucket],
});

4. 环境清理

在做出上述修改后，建议：

1. 删除 node_modules 目录
2. 删除可能存在的锁文件（package-lock.json 或 pnpm-lock.yaml）
3. 重新安装依赖
4. 重启开发服务器

最佳实践建议

1. Monorepo 管理：对于 SST 项目中的 monorepo，建议：

   • 明确区分应用和库的目录结构
   • 使用一致的工作区配置
   • 考虑使用更成熟的 monorepo 工具（如 Turborepo）管理复杂依赖

2. Next.js 部署：

   • 保持 Next.js 应用配置的独立性
   • 确保构建命令能在子目录中正确执行
   • 考虑使用 SST 的环境变量管理功能处理不同环境的配置

3. 调试技巧：

   • 使用 --print-logs 参数获取更详细的日志
   • 在出现问题时，尝试简化配置进行隔离测试
   • 关注 SST 和 Next.js 版本的兼容性

总结

在 SST 项目中部署非根目录的 Next.js 应用时，需要特别注意包管理器的统一性、应用命名的唯一性以及路径配置的简洁性。通过规范项目结构、统一工具链和简化配置，可以有效避免这类部署问题。对于 monorepo 项目，完善的工作区配置和清晰的目录结构是保证各应用独立部署的关键。