使用Turborepo时Next.js App Router服务端代码构建失败求助

可行的解决步骤 #

1. 统一Next.js版本 #

确保monorepo中所有Next.js项目的版本与原独立项目完全一致（包括patch版本），小版本差异可能导致App Router对服务端组件的识别逻辑异常。

2. 配置Turborepo依赖不hoist #

在根目录package.json中添加nohoist规则，避免服务端专属依赖被提升到根目录，导致客户端代码意外引入：

{
  "turbo": {
    "npmClient": "npm", // 根据你的包管理器替换为yarn/pnpm
    "nohoist": [
      "**/firebase-admin",
      "**/@google-cloud/**"
    ]
  }
}

3. 显式声明服务端外部包 #

在Next.js项目的next.config.js中配置serverComponentsExternalPackages，告诉Next.js这些包仅在服务端运行，无需打包到客户端：

/** @type {import('next').NextConfig} */
const nextConfig = {
  serverComponentsExternalPackages: ['firebase-admin', '@google-cloud/firestore'],
}

module.exports = nextConfig

4. 验证路径别名配置 #

检查项目的jsconfig.json或tsconfig.json，确保baseUrl和paths配置与原独立项目一致，避免模块解析错误导致服务端代码被客户端组件间接引入：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

5. 清理缓存后重新构建 #

• 删除所有项目的node_modules和.next目录
• 重新安装依赖：npm install（或对应包管理器的安装命令）
• 执行Turbo构建：turbo build

额外检查 #

确认@/app/api/firebase-admin模块仅被服务端组件/路由导入，没有被任何带'use client'指令的客户端组件间接引用。

内容的提问来源于stack exchange，提问作者Hacktisch