Turborepo改造公司已有项目，快到起飞✈️

前言

我目前在维护公司文档体系的代码，目前为止包含了：文档、excel、脑图、白板这几个单独的项目，还有一个主项目分别引入这几个单独的项目。不好维护并且有一些公共的方法需要在每个项目中重新写一次，刚好有看到 Turborepo，于是就尝试着将目前文档体系内的项目统一为 monorepo 的形式进行管理。

什么是 Turborepo

在了解 Turborepo 前先来了解下 monorepo。

在通用的开发场景中，人们希望各个项目之间能够足够的独立，各自的开发和发布不会产生太多的耦合，现在很多的项目也是出于这种考虑去拆成一个一个独立的子项目，在单独的代码仓库中进行管理，这就是我们常见的单代码仓库的开发模式。

但是上面的模式，在某些场景下就会显得低效和繁琐。比如一个仓库的代码被很多其他相关的仓库引用，那么只要这个仓库进行发版，所有依赖了这个代码的仓库也要跟着进行依赖升级和发版。如果把所有有依赖关系的代码都放到一个仓库中进行统一维护，当一个库变动时，其它的代码能自动的进行依赖升级，那么就能精简开发流程、提高开发效率。这种多包的代码仓库管理，就是 monorepo。

turbo 直译成中文的意思是"涡轮增压"：即一种车用内燃机或航空用发动机用来增加进气量的技术。与机械增压器相比，两者都可增加进入发动机的进气量，从而提高其效率。

官网介绍：Turborepo 是一个针对 JavaScript 和 TypeScript 代码库优化的智能构建系统。

如果直接说如何使用的话，那么感觉会有点乏味，那我们先看下如果不使用 Turborepo，我们之前是如何开发的，看完之后，再详细了解 Turborepo 的好处。

传统 multirepo 模式

首先看下，我们文档体系包含了这么多的子项目，如下：

那么，如果没有使用 monorepo 前，当我修复一个文档的 bug 时，我需要以下几步完成：

1. 修改xxx_word代码并提交到远程仓库；
2. 将xxx_word打包并发布到公司的 npm 仓库；
3. 在apps/web中更新xxx_word的版本号，重新构建；
4. 如果有其他项目使用xxx_word，也需要进行第三步操作。

修改其中一个项目的代码，就需要上面几个步骤，那如果有多个项目需要修改时，重复的操作越来越多，耗费的时间会越来越长。

从上面的例子可以看出，传统 multirepo 项目的弊端如下：

• 多项目代码共享难以实现，抽离成 npm 包的形式虽然可以解决，但带来时间上的消耗是无法避免的
• 版本管理乱：多应用版本管理混乱，有的已经 2.x，有的依然是 1.x；
• 项目配置不统一：如 Eslint、Husky 等代码校验工具需要单独配置，并且可能存在不配置的情况；
• 构建工具不统一，配置 CI/CD 构建部署的流程时难以统一。

那么，这时候就需要使用 Monorepo 来管理项目，解决以上可能出现的问题，如上图所示：

• 代码共享：主项目在apps/web下，依赖的子项目都在packages下，此时再对xxx_word代码修改时，主项目不用再手动修改子项目的版本号，而是依赖此代码库中的版本；
• 工具代码共享：可以将各项目都会用到的工具函数抽成一个个的方法，在xxx_libs统一管理，其他包直接引用即可；
• 配置共享： 实现 CI/CD 以及代码格式化工具的统一

Monorepo 的改造有多种方式实现，我们是用的 Turborepo 来实现，因为刚好那段时间它最火 🔥。

Turborepo 改造

根据官网 QuickStart介绍可以通过多种方式打造 Turborepo 项目：

1. 新建 Turborepo 项目
2. 将已有项目改造成 Turborepo
3. 将已有 monorepo 项目改造为 Turborepo

这里我们主要来讲一下对已有项目中添加 Turborepo 的改造。

已有项目改造

首先使用 vite 初始化一个 vue 项目：

接着，在当前项目中安装 turbo

1. 安装 turbo

   yarn add turbo -D
   # or
   npm install turbo -D
   # or
   pnpm add turbo -D

2. 在根目录下创建 turbo.json 文件

   Turborepo 所有相关的配置，都放入 turbo.json 这个配置项中，主要用于产物缓存，构建加速，构建流配置。

   {
     "$schema": "https://turbo.build/schema.json",
     "pipeline": {
       "build": {
         "outputs": ["dist/**"]
       },
       "lint": {}
     }
   }

   $schema：指定配置文件的 JSON Schema，它可以帮助你在编辑器中自动补全和校验配置项，固定值https://turborepo.org/schema.json

3. 修改 package.json 的 scripts 字段

    "scripts": {
     "dev": "vite",
     "build": "vite build",
     "lint": "vue-tsc",
     "preview": "vite preview"
   },

此时 Turborepo 就已经引入到使用 vite 创建的项目中，接下来做一些测试：

测试 turbo 缓存

上文说了 Turborepo 可以缓存任务的结果，从而提高任务速度，我们通过实践来看一下它是如何提高任务的速度。

如上图所示：首先第一次执行任务

turbo build

显示任务数量Tasks: 1 successful, 1 total，如果同时执行两个任务

turbo build lint

那么任务数量为Tasks: 2 successful, 2 total

第二次执行任务，此时可能会命中缓存，显示如上图的"二次构建"，出现彩色标签"FULL TURBO"时，说明此时没有真正的构建，而是从缓存中获取任务结果，可以看到时间缩减了 20 倍左右。

如何禁用缓存

当然，可能有一些任务需要禁用缓存，及每次都需要重新执行，可以通过以下方式实现：

• 禁止写入缓存：--no-cache

  turbo build lint --no-cache

  --no-cache可以禁止任务写入缓存，但不会禁止使用缓存 ，如果已经存在缓存时，那么--no-cache将不会产生任何效果。

• 禁止使用缓存：--force

  如果要禁用使用缓存，需要使用--force

  turbo build lint --force

  

• 禁用特定任务

  可以通过设置 pipeline task 中的cache字段禁用特定任务的缓存

  "pipeline": {
    "build": {
      "outputs": ["dist/**"]
    },
    "lint": {
      "cache": false
    }
  }

Monorepo 配置

假设一个 Monorepo 的项目如下所示：

根目录的 package.json 有一个 workspaces 字段，该字段用来让 Turborepo 知道目录下有哪些 workspace，这些 workspace 就交给 Turborepo 管理，应用程序放 apps 里面，apps 依赖包放 packages 里面。

"workspaces": [
  "apps/*",
  "packages/*"
],

修改根目录下的 package.json 的scripts

"scripts": {
  "build": "turbo run build",
  "dev": "turbo run dev --parallel",
}

在根目录 npm i，会把各 workspace 的 npm 依赖安装在根目录的 node_modules 中，而不是安装在各 workspace 的 node_modules 中；

全局安装

npm i vue -w

单独为某一个 workspace 安装 npm 依赖：

npm i vue-router -w=xxx

各 workspace 的 package.json 中的 name 字段很关键，它是 Turborepo 用来区分不同 workspace 的字段。

任务管道 pipeline

作用：任务管道也就是命令，用配置文件定义任务之间的关系，然后让 Turborepo 优化构建内容和时间。

pipeline 配置声明了在 monorepo 中哪些任务相互依赖，Turborepo 是通过 pipeline 来处理各个任务和他们的依赖关系的。

如果 Turbo 发现一个工作空间有一个 package.json scripts 对象中有一个匹配的键，它会在执行时将 pipeline 任务配置应用到那个 npm 脚本上。这样你就可以使用 pipeline 来设置你整个 Turborepo 的约定。

配置 pipeline

pipeline 中每个键名都可以通过运行turbo run来执行，并且可以使用dependsOn来执行当前管道的依赖项。

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false
    },
    "test": {
      "dependsOn": ["lint", "build"]
    }
  }
}

dependsOn 依赖

• 常规依赖

  如果一个任务的执行，只依赖自己包其他的任务，那么可以把依赖的任务放在 dependsOn 数组里

  {
    "turbo": {
      "pipeline": {
        "test": {
          "dependsOn": ["lint", "build"]
        }
      }
    }
  }

• 拓扑依赖

  可以通过^符号来显式声明该任务具有拓扑依赖性，需要依赖的包执行完相应的任务后才能开始执行自己的任务

  {
    "turbo": {
      "pipeline": {
        "build": {
          "dependsOn": ["^build"]
        }
      }
    }
  }

• 空依赖

  如果一个任务的 dependsOn 为undefined或者[]，那么表明这个任务可以在任意时间被执行

  {
    "turbo": {
      "pipeline": {
        "lint": {
          "outputs": []
        }
      }
    }
  }

比如web中 package.json 文件中 devDependencies 或者 dependencies 添加了web1和web2的依赖，此时执行turbo build命令运行web的打包命令时，会先等待web1和web2的build命令执行完成后，才会执行web中的build命令：

上面的 dependsOn 配置解释如下：

• build：依赖于其依赖项的 build 命令执行完成
• dev：依赖于其依赖项的 dev 命令执行完成
• test： 依赖于自身的 lint 和 build 命令执行完成
• lint：任何时候可以执行

其他字段

• env

  任务所依赖的环境变量，与 globalEnv 作用类似

• outputs

  构建产物输出的目录，当开启缓存时，Turbo 会将对应目录的产物进行缓存

• cache

  布尔类型，是否开启缓存，默认为 true

• inputs

  默认为[]，用于指定哪些文件的变化会触发任务的重新执行。

• outputMode

  设置输出日志记录的类型 full：默认设置，显示所有输出 hash-only: 只显示任务的 hash 值 new-only: 只显示没有命中缓存的任务输出 errors-only: 只显示失败的任务输出 none: 隐藏所有任务输出

• persistent

  如果当前任务是一个长时间运行的进程，比如 dev 命令，则可以设为 true

• globalEnv

  globalEnv 是一个字符串数组，用来指定一些环境变量作为全局的哈希依赖。这些环境变量的内容会被包含在全局的哈希算法中，影响所有任务的哈希值。例如，你可以在 globalEnv 中指定 GITHUB_TOKEN，这样当 GITHUB_TOKEN 的值发生变化时，所有任务的缓存都会失效。

  globalEnv 的值是从运行 turbo 命令的环境中获取的，你可以在终端中设置或者使用 .env 文件来管理。

• globalDependencies

  globalDependencies 是一个字符串数组，用来指定一些文件作为全局的哈希依赖。这些文件的内容会被包含在全局的哈希算法中，影响所有任务的哈希值，例如配置 tsconfig.json、jest.config.js，当这些文件内容有变化时，所有构建缓存将会失效

最后贴一下我们项目的 turbo 配置：

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "_build": {
      "description": "web 打包指令， 依赖的 word 的 pack 结果",
      "dependsOn": ["^_build", "^pack"],
      "outputs": ["dist/**"],
      "inputs": ["src/**", "public/**", "index.html", "*.config.js", "*.config.cjs", "*.config.ts"],
      "outputMode": "new-only"
    },
    "pack": {
      "description": "word 打包指令",
      "dependsOn": ["^pack"],
      "outputs": ["dist/**"],
      "inputs": ["src/**", "public/**", "packages/**", "*.config.js", "*.config.cjs", "*.config.ts"],
      "outputMode": "new-only"
    },
    "lint": {
      "outputs": []
    },
    "_dev": {
      "description": "调试指令； web 依赖的 word 的 pack 结果",
      "dependsOn": ["^pack"],
      "cache": false
    }
  },
  "globalEnv": ["VITE_API_URL", "VUE_APP_*", "VITE_*"]
}

Turborepo 优势

• 增量构建：缓存构建内容，并跳过已经计算过的内容，通过增量构建来提高构建速度
• 内容 hash：通过文件内容计算出来的 hash 来判断文件是否需要进行构建
• 云缓存：可以和团队成员共享 CI/CD 的云构建缓存，来实现更快的构建
• 并行执行：在不浪费空闲 CPU 的情况下，以最大并行数量来进行构建
• 任务管道：通过定义任务之间的关系，让 Turborepo 优化构建的内容和时间
• 约定式配置：通过约定来降低配置的复杂度，只需要几行简单的 JSON 就能完成配置

总结

Turborepo 是一个基于 Vite 的构建工具，可以实现构建的增量化、内容哈希、云缓存、并行执行、任务管道、约定式配置等功能，在我们项目中使用一段时间后，感觉速度嘎嘎快 ✨，如果大家有 Monorepo 的需求，推荐大家使用 Turborepo 。

以上就是本文的全部内容，希望这篇文章对你有所帮助，欢迎点赞和收藏 🙏，如果发现有什么错误或者更好的解决方案及建议，欢迎随时联系。