Lerna多包管理实战教程：从入门到精通

前言

在现代前端开发中，随着项目规模的不断扩大和业务复杂度的提升，单一代码仓库（Monorepo）的管理模式越来越受到开发者的青睐。Lerna作为最流行的Monorepo管理工具之一，帮助开发者更高效地管理多个相互依赖的JavaScript包。本文将深入探讨Lerna的核心概念、工作原理以及实际应用，通过详细的实战案例带领读者全面掌握Lerna的使用技巧。

什么是Lerna？

Lerna是一个用于管理包含多个包/模块的JavaScript项目的工具，它优化了使用Git和npm管理多包仓库的工作流程。通过Lerna，开发者可以在一个代码仓库中管理多个相互关联的包，同时保持这些包的独立版本控制和发布流程。

Lerna的核心特性

1. 自动化包链接：自动处理包之间的依赖关系，将本地包链接到彼此
2. 版本管理：支持统一版本管理和独立版本管理两种模式
3. 发布管理：简化多包发布流程，自动更新依赖关系
4. 变更检测：智能检测包的变化，只构建和发布发生变化的包
5. 工作流优化：提供丰富的命令行工具，优化开发工作流程

Lerna的安装与配置

环境准备

在开始使用Lerna之前，需要确保系统中已安装Node.js（建议版本12.0.0以上）和Git。可以通过以下命令检查当前环境：

node --version
npm --version
git --version

安装Lerna

Lerna可以通过npm或yarn全局安装：

# 使用npm安装
npm install -g lerna

# 使用yarn安装
yarn global add lerna

初始化Lerna项目

创建一个新的目录并初始化Lerna项目：

# 创建项目目录
mkdir my-lerna-project
cd my-lerna-project

# 初始化Lerna项目
lerna init

初始化完成后，项目结构如下：

my-lerna-project/
├── packages/
│   ├── package-a/
│   └── package-b/
├── lerna.json
├── package.json
└── README.md

Lerna配置文件详解

Lerna的主要配置文件是lerna.json，它包含了项目的配置信息：

{
  "packages": ["packages/*"],
  "version": "independent",
  "npmClient": "npm",
  "command": {
    "publish": {
      "ignoreChanges": ["*.md"],
      "message": "chore(release): publish"
    },
    "bootstrap": {
      "ignore": "component-*",
      "npmClientArgs": ["--no-package-lock"]
    }
  }
}

配置项说明：

• packages：定义包的位置模式
• version：版本管理模式，independent表示独立版本，fixed表示统一版本
• npmClient：指定包管理器，可以是npm、yarn或pnpm
• command：各种命令的配置选项

Lerna核心概念解析

包管理策略

Lerna支持两种包管理策略：

固定模式（Fixed Mode） 所有包共享同一个版本号，当任何一个包发生变化时，所有包都会发布新版本。这种模式适用于紧密耦合的包集合。

独立模式（Independent Mode） 每个包都有自己独立的版本号，Lerna会根据包的变更情况智能地更新版本。这种模式适用于相对独立的包集合。

工作空间（Workspace）

Lerna利用npm或yarn的工作空间功能来优化本地包的链接。在package.json中配置workspaces：

{
  "private": true,
  "workspaces": [
    "packages/*"
  ]
}

包依赖管理

Lerna自动处理包之间的依赖关系。当包A依赖包B时，Lerna会在node_modules中创建符号链接，指向本地的包B，而不是从npm仓库下载。

Lerna常用命令详解

初始化命令

# 初始化新的Lerna仓库
lerna init

# 使用独立版本模式初始化
lerna init --independent

包管理命令

# 创建新包
lerna create <package-name>

# 列出所有包
lerna list

# 查看发生变化的包
lerna changed

# 清理所有包的node_modules
lerna clean

依赖管理命令

# 为所有包安装依赖并链接本地包
lerna bootstrap

# 为指定包添加依赖
lerna add <package> [--dev] [--scope=<package>]

# 为所有包添加相同的依赖
lerna add <package> --all

脚本执行命令

# 在所有包中运行npm脚本
lerna run <script>

# 在指定包中运行脚本
lerna run <script> --scope=<package>

# 并行运行脚本
lerna run <script> --parallel

版本管理与发布

# 创建新版本
lerna version

# 发布包到npm
lerna publish from-package

# 发布当前提交中标记的包
lerna publish from-git

实战案例：构建组件库

让我们通过一个完整的实战案例来演示如何使用Lerna管理一个UI组件库项目。

项目结构设计

假设我们要构建一个名为awesome-ui的组件库，包含以下包：

awesome-ui/
├── packages/
│   ├── button/          # 按钮组件
│   ├── input/           # 输入框组件
│   ├── modal/           # 模态框组件
│   ├── theme/           # 主题包
│   └── utils/           # 工具函数包
├── docs/                # 文档网站
├── examples/            # 示例项目
└── scripts/             # 构建脚本

初始化项目

# 创建项目目录
mkdir awesome-ui
cd awesome-ui

# 初始化Git仓库
git init

# 初始化Lerna项目
lerna init --independent

# 创建根目录package.json
npm init -y

配置工作空间

在根目录的package.json中添加workspaces配置：

{
  "name": "awesome-ui",
  "private": true,
  "workspaces": [
    "packages/*",
    "docs",
    "examples"
  ],
  "scripts": {
    "bootstrap": "lerna bootstrap",
    "build": "lerna run build",
    "test": "lerna run test",
    "clean": "lerna run clean --parallel",
    "publish": "lerna publish"
  }
}

创建组件包

使用Lerna创建按钮组件包：

lerna create button --yes

编辑packages/button/package.json：

{
  "name": "@awesome-ui/button",
  "version": "1.0.0",
  "description": "A beautiful button component",
  "main": "dist/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "rollup -c",
    "dev": "rollup -c -w",
    "test": "jest",
    "clean": "rimraf dist"
  },
  "dependencies": {
    "@awesome-ui/theme": "^1.0.0"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  }
}

创建按钮组件的源代码packages/button/src/Button.tsx：

import React from 'react';
import { useTheme } from '@awesome-ui/theme';
import './Button.css';

interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  onClick?: () => void;
}

export const Button: React.FC<ButtonProps> = ({
  children,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  onClick,
}) => {
  const theme = useTheme();

  return (
    <button
      className={`btn btn--${variant} btn--${size}`}
      disabled={disabled}
      onClick={onClick}
      style={{
        backgroundColor: theme.colors[variant],
        color: theme.colors.text,
      }}
    >
      {children}
    </button>
  );
};

配置构建工具

在根目录创建Rollup配置文件rollup.config.js：

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import { terser } from 'rollup-plugin-terser';
import peerDepsExternal from 'rollup-plugin-peer-deps-external';

export default {
  input: 'src/index.ts',
  output: [
    {
      file: 'dist/index.js',
      format: 'cjs',
      exports: 'named',
    },
    {
      file: 'dist/esm/index.js',
      format: 'esm',
    },
  ],
  plugins: [
    peerD