《从零搭建 Next.js + NestJS 全栈项目：踩坑实录》

# 从零搭建 Next.js + NestJS 全栈项目：Turborepo + pnpm 踩坑实录与最佳实践

> **项目 GitHub 地址**：[https://github.com/yourname/freemonitor-app](https://github.com/yourname/freemonitor-app)  
> **技术栈**：Next.js + NestJS + Turborepo + pnpm + TypeScript + Tailwind CSS + Docker  
> **关键词**：`#Next.js` `#NestJS` `#Turborepo` `#pnpm` `#全栈开发` `#工程化`

---

## 🚀 引言

最近我着手开发一个监控平台 `FreeMonitor`，决定采用 **Next.js + NestJS** 作为前后端技术栈，并使用 **Turborepo + pnpm** 构建 Monorepo 项目。

本以为初始化脚手架后就能快速开发，结果在 `pnpm install`、`turbo run dev` 等环节踩了无数坑。经过连续调试，终于跑通了前后端一体化开发流程。

本文将**完整记录我遇到的所有问题、错误信息、错误操作和最终解决方案**，希望能帮你少走弯路。

---

## 🏗️ 项目初始化

使用 `create-next-app` 初始化前端，Turborepo 管理多项目：

```bash
# 初始化前端
pnpm create next-app@latest apps/frontend --use-pnpm --typescript --tailwind --eslint --app --src-dir --import-alias="@/*"

# 安装 Turborepo 到根目录
pnpm add -D -w turbo typescript @types/node

项目结构如下：

freemonitor-app/
├── apps/
│   ├── frontend/     # Next.js 前端
│   └── backend/      # NestJS 后端
├── packages/
│   └── types/        # 共享类型
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

---

🧩 遇到的问题与解决方案

❌ 1. ERR_PNPM_WORKSPACE_PKG_NOT_FOUND：误用 workspace:*

报错信息：

ERR_PNPM_WORKSPACE_PKG_NOT_FOUND  In packages/types: "typescript@workspace:*" is in the dependencies but no package named "typescript" is present in the workspace

错误原因 ：
typescript 是 npm 包，不是 workspace 内部包，不能用 workspace:*。

错误操作：

"devDependencies": {
  "typescript": "workspace:*"
}

✅ 解决方案 ：

改为从 npm 安装：

"devDependencies": {
  "typescript": "^5.9.2"
}

---

❌ 2. ERR_PNPM_ADDING_TO_ROOT：未明确依赖安装位置

报错信息：

ERR_PNPM_ADDING_TO_ROOT  Running this command will add the dependency to the workspace root...

原因：pnpm 提示你是否要安装到根目录。

✅ 解决方案 ：

明确使用 -w：

pnpm add -D -w tailwindcss postcss autoprefixer

---

❌ 3. WARN Ignoring broken lockfile：pnpm 版本不兼容

报错信息：

WARN  Ignoring broken lockfile at /.../pnpm-lock.yaml not compatible with current pnpm

原因 ：当前 pnpm@8.15.0 无法解析由 pnpm@10+ 生成的 lockfile。

✅ 解决方案 ：

升级 pnpm：

pnpm add -g pnpm@10.15.0

并在 package.json 中声明：

"packageManager": "pnpm@10.15.0"

---

❌ 4. Configuring Next.js via 'next.config.ts' is not supported

报错信息：

Error: Configuring Next.js via 'next.config.ts' is not supported.

原因 ：Next.js 不支持 next.config.ts。

✅ 解决方案 ：

重命名为 next.config.js，并使用 JSDoc 类型提示：

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
}

module.exports = nextConfig

---

❌ 5. Module not found: Can't resolve 'tailwindcss'

报错信息：

Module not found: Can't resolve 'tailwindcss'
Import trace for requested module: ./src/app/globals.css

原因 ：tailwindcss 未正确安装或未被 PostCSS 找到。

✅ 解决方案 ：

在根目录安装构建工具：

pnpm add -D -w tailwindcss postcss autoprefixer

---

❌ 6. Unknown font 'Geist'

报错信息：

`next/font` error: Unknown font `Geist`

原因 ：Geist 不是 Google Fonts 字体，而是本地 .woff 文件。

✅ 解决方案 ：

使用 next/font/local 加载本地字体：

import localFont from 'next/font/local'

const geistSans = localFont({
  src: './fonts/GeistVF.woff',
  variable: '--font-geist-sans',
})

---

❌ 7. turbo_json_parse_error: Found an unknown key 'tasks'

报错信息：

turbo_json_parse_error
× Found an unknown key 'tasks'.

原因 ：$schema URL 有空格或旧版 turbo 无法解析 schema。

✅ 解决方案 ：
升级 turbo 到 2.5.6，并使用稳定 URL：

{
  "$schema": "https://turborepo.com/schema.v2.json",
  "tasks": {
    "dev": {
      "persistent": true
    },
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    }
  }
}

✅ 升级后可安全保留 $schema，支持 VS Code 智能提示。

---

❌ 8. 后端服务未启动，无日志

现象 ：pnpm dev 执行，但后端无 console.log("🚀 Backend server running...")

原因 ：apps/backend/package.json 缺少 dev 脚本。

✅ 解决方案 ：

添加 dev 脚本：

"scripts": {
  "dev": "npm run start:dev",
  "start:dev": "ts-node-dev --respawn --transpile-only src/main.ts"
}

---

✅ 最终配置总结

turbo.json（推荐）

{
  "$schema": "https://turborepo.com/schema.v2.json",
  "tasks": {
    "dev": {
      "persistent": true
    },
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    }
  }
}

apps/backend/package.json

"scripts": {
  "dev": "npm run start:dev",
  "start:dev": "ts-node-dev --respawn --transpile-only src/main.ts"
}

.gitignore

node_modules/
.pnpm/
.next/
dist/
.turbo/
.env.local
.env.development
!.env.example

---