Turborepo 实战:用 with-vue-nuxt 示例构建 Vue 3 + Nuxt 共享 UI 库的 Monorepo

原创2026-09-19 12:29:511,870 阅读
文章标签:构建工具开发工具CLI

Turborepo 实战:用 with-vue-nuxt 示例构建 Vue 3 + Nuxt 共享 UI 库的 Monorepo

这篇技术指南围绕 Turborepo 官方示例仓库中的 with-vue-nuxt 模板展开,完整讲解如何用 Turborepo 编排一个同时包含 Nuxt 应用、Vite + Vue 3 应用以及共享 Vue 组件库的 pnpm monorepo。读完本文,你将掌握该模板的目录结构、turbo.json 任务编排语义、跨应用共享 ui 包的方式,以及构建、开发与远程缓存的实际用法,可直接照搬到自己的 Vue 技术栈 monorepo 项目中。

示例定位:社区维护的 Vue/Nuxt Monorepo 模板

with-vue-nuxt 是 Turborepo 仓库中的一个示例工程,其元信息(见 examples/with-vue-nuxt/meta.json)将其定位为 "Monorepo with Vue and Nuxt, sharing a UI Library",并由社区维护(maintainedByCoreTeam: false)。这意味着它演示的是一种真实、可复制的组织方式,而不是演示性的玩具工程:

  • 两个独立应用:一个基于 Vite 的 Vue 3 单页应用(web)与一个基于 Nuxt 的服务端渲染应用(docs);
  • 一个共享 UI 库:ui 包同时被两个应用以 workspace:* 协议依赖;
  • 完整的工程化配套:共享 TypeScript 配置、共享 ESLint 扁平配置、pnpm workspace 与 Turborepo 任务编排。

整仓采用 pnpm 作为包管理器(packageManager: pnpm@11.24.0,见 examples/with-vue-nuxt/package.json),workspace 声明在 examples/with-vue-nuxt/pnpm-workspace.yaml:

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

allowBuilds:
  esbuild: true
  unrs-resolver: true

即 apps 与 packages 目录下的所有子目录都是独立的 workspace 包,这是 Turbo 生态中最标准的 monorepo 布局约定。

快速启动:一条命令生成完整工程

模板的官方使用方式是借助 create-turbo 脚手架,从示例直接生成项目:

npx create-turbo@latest -e with-vue-nuxt

执行后,脚手架会把整个示例(两个应用、三个包、根级 turbo.json 与 workspace 配置)复制到当前目录并安装依赖。安装完成后即可继续下文的任务操作。

仓库结构:Apps 与 Packages 全景

按 README 与源码,该模板的顶层结构如下:

目录/包 说明
apps/docs Nuxt 应用(当前使用 Nuxt 4),默认运行在 3001 端口
apps/web Vue 3 + Vite 应用,默认运行在 3000 端口
packages/ui 被 web 与 docs 共享的 Vue 组件库
packages/eslint-config-custom 面向 Vue 包的共享扁平 ESLint 配置
packages/tsconfig 共享的 tsconfig.json(含 base.json、vue.json、nuxt.json)

各包/应用均为 100% TypeScript。工程化工具链由 TypeScript 负责静态类型检查、ESLint 负责代码规范、Prettier 负责格式化——根级 package.json 中的 format 脚本即为 Prettier 全局格式化:

"scripts": {
  "build": "turbo run build",
  "dev": "turbo run dev",
  "lint": "turbo run lint",
  "format": "prettier --write \"**/*.{ts,tsx,md}\""
}

任务编排核心:turbo.json 逐项拆解

模板的 Turborepo 配置集中在 examples/with-vue-nuxt/turbo.json,是理解整个示例行为的关键:

{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".nuxt/**", ".output/**", "dist/**"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

各配置项的实际语义如下:

  • build.dependsOn: ["^build"]:声明 build 任务依赖其拓扑依赖的 build 任务(^ 前缀表示“上游依赖”)。这保证 ui 包先于 web、docs 构建完成,Turborepo 会据此自动计算并行的构建调度顺序;
  • build.inputs: ["$TURBO_DEFAULT$", ".env*"]:定义参与缓存哈希的文件集合。$TURBO_DEFAULT$ 是内置占位符(默认覆盖 package.json、turbo.json 等全局关键文件),.env* 将环境变量文件纳入哈希,任何 .env 变化都会使缓存失效,避免“改了环境变量却命中旧缓存”的经典问题;
  • build.outputs: [".nuxt/**", ".output/**", "dist/**"]:声明构建产物目录。.nuxt 与 .output 对应 Nuxt 构建中间产物与最终产物,dist 对应 Vite 构建产物。Turborepo 只缓存这些目录,命中缓存时直接恢复产物并跳过实际构建;
  • lint: {}:空配置即采用默认行为——每个包的 lint 脚本独立执行,输入变化才重跑,正常参与缓存;
  • dev: { cache: false, persistent: true }:开发服务器既不缓存也不退出。persistent: true 告诉 Turborepo 该任务会长时间占用进程,从而避免调度器在它“未结束”时误判失败或重复拉起,同时 turbo run dev 会把 web(3000)与 docs(3001)两个开发服务器并行拉起。

应用层细节:Nuxt 与 Vite 的差异化脚本设计

Nuxt 应用 apps/docs

其脚本定义在 examples/with-vue-nuxt/apps/docs/package.json:

"scripts": {
  "build": "nuxt build",
  "dev": "nuxt dev --port 3001",
  "generate": "nuxt generate",
  "preview": "nuxt preview",
  "postinstall": "nuxt prepare",
  "lint": "eslint ."
}

要点:dev 显式固定 --port 3001,与 web 的 3000 错开端口,保证 turbo run dev 并行启动时互不冲突;postinstall 中的 nuxt prepare 会在依赖安装后自动生成 Nuxt 的类型声明与虚拟文件,是 Nuxt 3/4 工程在 monorepo 中的常见实践。Nuxt 配置 examples/with-vue-nuxt/apps/docs/nuxt.config.ts 启用了 @nuxt/eslint 模块与 devtools:

export default defineNuxtConfig({
  modules: ["@nuxt/eslint"],
  devtools: { enabled: true },
});

应用入口 examples/with-vue-nuxt/apps/docs/app.vue 直接演示了跨包引用的写法——从 ui 导入 Page 组件并注入当前包名:

<script setup lang="ts">
import { Page } from "ui";
import { name } from "./package.json";

useHead({
  title: "Create Turborepo (vue-nuxt:docs)",
  meta: [{ name: "description", content: "Generated by create turbo" }],
});
</script>

<template>
  <Page :app-name="name" />
</template>

注意这里的 import { Page } from "ui":依赖名 ui 直接指向 workspace 包,无需相对路径穿越,这正是 monorepo 包引用模式的直观体现。

Vue 3 应用 apps/web

脚本定义在 examples/with-vue-nuxt/apps/web/package.json:

"scripts": {
  "dev": "vite --port 3000",
  "build": "run-p check-types \"build-only {@}\" --",
  "preview": "vite preview",
  "build-only": "vite build",
  "check-types": "vue-tsc --noEmit -p tsconfig.app.json --composite false",
  "lint": "eslint ."
}

构建链路值得注意:build 使用 npm-run-all2 的 run-p 并行执行 check-types(vue-tsc 类型检查,--composite false 用于规避 project references 下的增量编译约束)与 build-only(vite build),把“类型检查 + 打包”组合成一次 Turbo 可缓存的原子任务。Vite 配置 examples/with-vue-nuxt/apps/web/vite.config.ts 注册了 @vitejs/plugin-vue 并配置了 @ 指向 src 的路径别名:

import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

共享 UI 库 packages/ui

ui 包的公共入口是 examples/with-vue-nuxt/packages/ui/index.ts,以命名导出暴露三个组件:

import Card from "./src/card.vue";
import Gradient from "./src/gradient.vue";
import Page from "./src/page.vue";

export { Card, Gradient, Page };

其中 page.vue 是一个包含品牌展示区、链接卡片网格与响应式样式(含 prefers-reduced-motion 无障碍适配与移动端断点)的完整页面组件,通过 defineProps<{ appName: string }>() 接收应用名。web 与 docs 两个应用都通过 "ui": "workspace:*" 依赖它,做到“一套组件、两端复用”。这正是 Turborepo build.dependsOn: ["^build"] 发挥作用的最小闭环:ui 作为上游先构建,两个应用再消费其产物。

日常开发工作流

在仓库根目录执行(以下命令均基于根级 examples/with-vue-nuxt/package.json 的脚本):

开发模式(并行启动两个 dev server):

pnpm dev

内部执行 turbo run dev,依据 turbo.json 中 dev 的 persistent: true 与 cache: false 语义并行常驻运行:web 在 http://localhost:3000,docs 在 http://localhost:3001。

构建全部应用与包:

pnpm build

内部执行 turbo run build,Turborepo 会按 dependsOn: ["^build"] 先构建 ui、tsconfig 等依赖,再并行构建两个应用,并将产物按 outputs 声明缓存(.nuxt/**、.output/**、dist/**)。二次构建若输入未变化将直接命中本地缓存,秒级完成。

代码检查与格式化:

pnpm lint    # 等价于 turbo run lint,逐个包执行 eslint
pnpm format  # prettier --write "**/*.{ts,tsx,md}" 全仓格式化

远程缓存:让构建产物跨机器共享

模板默认使用 Turborepo 的本地缓存;若需在团队成员与 CI/CD 之间共享缓存产物,可按 README 中的指引启用 Remote Caching(以 Vercel Remote Cache 为例):

  1. 登录并认证 Turborepo CLI 与 Vercel 账号:

    pnpm turbo login
    
  2. 在仓库根目录将当前仓库链接到远程缓存:

    pnpm turbo link
    

启用后,任意机器上以相同输入执行 turbo run build,都可直接拉取远程缓存的构建产物,跳过重复计算——在 CI 上体现为构建时间的大幅缩短。不配置远程缓存时,Turborepo 仍会在本地(node_modules/.cache/turbo 或系统缓存目录)正常缓存,功能不受影响。

进阶:基于模板扩展自己的 Vue monorepo

从源码结构可以推断出几条清晰的扩展路径:

  • 新增一个 Vue 应用:在 apps/ 下复制 web 的结构,保持 pnpm-workspace.yaml 的 apps/* 通配即可被自动识别,无需改动根级 turbo.json——build、dev、lint 任务会自动覆盖新包;
  • 新增一个共享包:在 packages/ 下仿照 ui 建立新包,并在消费方 package.json 中声明 "your-pkg": "workspace:*";
  • 细化任务:例如为 test、typecheck 增加任务配置,或按需调整 inputs(如把 src/** 加入哈希集合)以提升缓存命中精度。

需要说明的是,本模板属于社区维护示例,其依赖版本(Nuxt 4、Vite 8、pnpm 11 等)以仓库当前实际内容为准,若迁移到自己的工程请按需对齐版本。

登录后查看全文
turbo