如何将TurboRepo中的Next.js应用打包为独立可部署版本？

问题背景 #

使用TurboRepo开发个人项目已一年多，认可其部署测试项目、包的高效性，但单独部署应用时遇到瓶颈，未在官方文档及网络找到解决方案。

预期目标：生成包含应用代码及所有依赖（包括workspace:*依赖）的构建包，实现应用独立部署。

目前在TurboRepo内构建运行应用可行，但产物仍依赖workspace:*包。将应用迁移至Docker镜像、新目录等隔离环境时，会出现无法引用部分workspace:*依赖的问题。

曾在next.config.mjs中添加output: "standalone"配置，.next目录下生成/standalone文件夹，结构如下（应用名称为docs-template-mar-25）：

.next/
server/
standalone/
├── apps/
│   └── docs-template-mar-25/ # 应用构建产物
│       ├── .next/
│       ├── node_modules/
│       ├── package.json         # 仍包含workspace:*依赖
│       └── server.js
├── node_modules/
├── packages/
└── package.json

static/
types/
package.json
...其他文件

.next文件夹结构示意图：

解决方案 #

1. 调整TurboRepo构建流水线 #

在turbo.json中为应用构建任务添加依赖前置构建，确保所有workspace包先完成构建：

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    }
  }
}

2. 优化Next.js的输出追踪配置 #

在next.config.mjs中指定输出追踪根目录，让Next.js识别并打包workspace内的依赖：

const path = require('path');

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  experimental: {
    outputFileTracingRoot: path.join(__dirname, "../../"),
  },
};

export default nextConfig;

3. 替换package.json中的workspace依赖 #

编写构建后脚本，将应用产物中的workspace:*依赖替换为对应包的实际版本：
创建scripts/post-build.js文件：

const fs = require('fs');
const path = require('path');

// 目标package.json路径
const targetPkgPath = path.join(__dirname, '../.next/standalone/apps/docs-template-mar-25/package.json');
const pkg = require(targetPkgPath);

// 遍历依赖，替换workspace引用
for (const [depName, depVersion] of Object.entries(pkg.dependencies)) {
  if (depVersion.startsWith('workspace:')) {
    // 读取对应workspace包的版本
    const workspacePkgPath = path.join(__dirname, '../../packages', depName, 'package.json');
    const workspacePkg = require(workspacePkgPath);
    pkg.dependencies[depName] = workspacePkg.version;
  }
}

// 写入修改后的package.json
fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2));

在应用的package.json中添加构建后脚本：

{
  "scripts": {
    "postbuild": "node scripts/post-build.js"
  }
}

4. 验证独立部署可行性 #

构建完成后，进入standalone/apps/docs-template-mar-25目录，执行npm install（此时依赖已无workspace引用），然后启动应用测试：

cd .next/standalone/apps/docs-template-mar-25
npm install
node server.js

确认应用能正常运行后，即可将该目录打包用于Docker或其他隔离环境部署。

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