lerna 从0到1

简介

Lerna 是一种工具，针对使用 git 和 npm 管理多软件包代码仓库的工作流程进行优化。多包管理器

背景

当前手上需要同时维护几个npm工具包，有些包与包之间存在依赖管理。经常更新某个底层包后，需要同时更新上层包。维护的心智负担着实不小。所以希望通过 lerna 多包管理器，提高npm包的维护效率。

lerna 4.0.0

DEMO 目录

root/
- lerna.json lerna 配置
- package.json
- packages/ npm包集合
  - pkg-ts npm 子包
  - pkg-es6

安装

npm i -g lerna

初始化

首先进入根目录，调用初始化命令init 。 lerna 将为我们生成基础的项目目录和配置.

lerna init

image.png

模式

lerna 对包的有两种处理模式, 固定模式独立模式

固定模式

管理下的所有包使用 lerna.json 的统一版本线。
例如我们存在包 A: v1.0.0 , b: v2.0.0 lerna.json v1.0.0。发布新版本时，更新版本为v1.1.0。 A , B , lerna.json 的版本号都将统一为 v1.1.0。
这里模式适合，包集合统一依赖，包集合作为整体工具来使用

独立模式

与固定模式相反, 独立模式允许各个包独立管理自己的版本。
此时 lerna.json 中的 version 字段值为 "independent"

模式设置

// 方式一 初始化时, 添加 -i 或 --independent 参数
lerna init -i

// 方式二 直接配置lerna.json
// lerna.json
{
  ...
  "version": "independent"
}

配置文件

lerna.json 配置文件中，我们设置详细的自定义配置。

{
  // 统一版本号,   
  "version": "0.0.0",
  // 包管理工具类型, npm, yarn, cnpm, 之后的命令将使用该配置, 例如依赖安装
  "npmClient": "npm",
  // 包目录, 可以指定多个目录或目录匹配规则。
  "packages": [
      "packages/*" // 需要管理的包都放在 packages/ 目录下 
   ],
  // 是否开启"工作空间"
  "useWorkspaces": false,
  // 命令行配置
  // 调用命令行时，将合并该配置内容执行相关命名
  // 命令可配置项于命令行一一对应
  "command": {
    // 命令名称
    "bootstrap": {
      // 命令参数名: 参数值 
      "ignore": "component-*",
      // 等价于命令 lerna bootstrap --ignore=component-*
    }
    ...
  }
}

配置文件可以认为保存我们经常使用的命令操作配置，简化使用。命令使用及配置查看基础命令, 进阶命令

基础命令

学lerna 主要学习的是lerna 常用管理命令, 例如依赖安装，版本管理，发包等。

init 初始化

用来初始化lerna 项目

lerna init

参数:

-i or --independent 使用独立模式, 默认固定模式
--exact 使用固定模式

create 创建包

将在包集合目录下，新建包基础目录结构 lerna create [名称] [集合目录]

lerna create utils

参数：

name 名称
loc 包集合目录, 单一包集合时为可选。

// leran.json 
{
  "packages": [
    // 存在多个包集合
    "source/*", 
     "utils/*",
  ]
}

// shell
// 在指定包集合中新增day包
lerna create day utils

-- yes 跳过交互配置

learna create day --yes

--bin 是否为可执行包
--description 包描述
--dependencies 依赖列表
--es-module 初始化为ES6 模块
--homepage 包首页地址
--keywords npm 查询关键子列表
--license 开源许可
--private 私有包
--registry npm源
--tag 标签

lerna create day --description=一段描述

boostrap 安装依赖

为所有包安装依赖, 并链接相关的本地依赖包。

lerna boostrap

参数:

--ignore 忽略

安装时，跳过某些包的依赖安装。lerna bootstrap --ignore [包命|包命匹配规则]
这里的包命指的是 package.json 中 name 属性定义的包名

// 不为 pkg-ts 安装依赖
lerna bootstrap --ignore pkg-ts
// 不为 以 pkg- 开头的包安装依赖
lerna bootstrap --ignore pkg-*

--hoist 提升

正常情况下，依赖安装在对应的包目录下。有时候多个包有相同的依赖或我们希望依赖相同的包实例, 可以将依赖包安装到根目录。

lerna bootstrap --hoist

--nohoist

依赖提升时，忽略部分包, --nohoist=[依赖包名 | 依赖包命匹配规则]

// 依赖提升，但不提升babe依赖
lerna bootstrap --hoist --nohoist=babel-*

--strict 严格模式

相同依赖包的版本不兼容时，将报错并终止安装

lerna bootstrap --hoist --strict

--ignore-scripts

忽略生命周期钩子的调用

lerna bootstrap --ignore-scripts

--npm-client

包管理工具类型

// 使用 yarn 安装依赖
lerna bootstrap --npm-client=yarn

--use-workspaces

开启workspaces

lerna bootstrap --use-workspaces

同时需要在根目录package.json 配置 workspaces

// root/package.json
{
  "workspaces": ["packages/*"]
}

--force-local

始终使用本地依赖，无论版本是否匹配

lerna bootstrap --force-local

--no-ci / --ci

npm ci 开启or关闭

lerna bootstrap --no-ci
or
lerna bootstrap --ci

clean

清理所有依赖, 删除所有包内node_modules

lerna clean

参数:

--yes

不做确认提示

lerna clean --yes

list

显示包列表

lerna list
// or 
lerna ls

参数

--json

以json的形式显示

--all | -a

显示所有包，包括私有包

--long | -l

显示扩展信息

--parseable

显示包路径列表

--toposort

按照依赖关系显示

--graph

按照依赖关系以json形式显示

进阶命令

publish

发包

learn publish

参数:

form-git

根据 git commit 的 annotaed tag 确定包版本，进行发包

lerna publish from-git

from-package

根据 package.json 的版本，进行发包

lerna publish from-package

--canary

根据上次版本计算出新的版本号，进行发包。不会进入版本交互模式中

lerna publish --canary

--contents

指定发布的包内容, 类似 package.json 的 files 属性

lern publish --contents lib

--dist -tag

新增 dist-tag 标签

lerna publish --dist-tag next

--no-verify-access

禁止npm权限校验

lerna publish --no-verify-access

--preid

为--canary 提供指定的发布标识符

lerna publish --canary
# uses the next semantic prerelease version, e.g.
# 1.0.0 => 1.0.1-alpha.0


lerna publish --canary --preid next
# uses the next semantic prerelease version with a specific prerelease identifier, e.g.
# 1.0.0 => 1.0.1-next.0

--pre-dist-tag

--dist-tag 的预发布版本

lerna publish --pre-dist-tag next

--registry

使用指定源发布

lerna publish --registry https://cnpmjs.org

--tag-version-prefix

自定义版本前缀，默认: v

# locally
lerna version --tag-version-prefix=''


# on ci
lerna publish from-git --tag-version-prefix=''

--ignore-scripts

禁用生命周期钩子脚本

lerna publish --ignory-scripts

--yes

跳过确认

lerna publish --canary --yes

add

安装包, 类似 npm i package,

// 为所有包安装 dayjs 依赖
lerna add dayjs

参数:

--scope

限制安装范围

// 只为包 pkg-1 安装依赖 dayjs
lerna add dayjs --scope=pkg-1
// 等价于 cd pkg-1/ && npm i dayjs

--dev

开发依赖

lerna add rollup --dev

--exact

使用精确版本，而不是版本范围。
例如 默认添加版本号: ^1.0.1， 精确版本： 1.0.1

lerna add --exact

--peer

添加到 peerDependencies 中

lerna add vue --peer

--registry

使用指定源安装

lerna add vue --registry http://r.npm.taobao.org/

--no-bootstrap

跳过 bootstrap

lerna add rollup

version

创建新的包版本
执行流程:

1. 标识自上次标记发布以来已更新的包。
1. 新版本的提示。
1. 修改包元数据，执行各个包内的生命周期钩子。
1. 提交修改和标签。
1. 推送到 git 远端分支。

lerna version

参数

bump

版本更新方式

major 主版本
mior 副版本
patch 修复版本
premajor 预发布主版本
preminor 预发布副版本
prepatch 预发布修复版本
prerelease 预发布版

参数：
@lerna/version（翻译

run

指定package.json 脚本命令

lerna run build

参数:

--stream

显示子进程输出

lerna run <命令> --stream

--parallel

显示子进程输出, 忽略排序

lerna run <命令> --parallel

--no-bail

禁止非零退出

lerna run --no-bail test

--no-prefix

禁止包前缀

lerna run --no-prefix

--profile

生成性能分析文件

lerna run build --profile

--profile-localtion

生成并保存性能分析文件

lerna run build --profile-localtion

exec

在每个包中，执行命令行, run 命令的底层命令

lerna exec -- echo xx > logs.text

--scope

限制命令作用范围

lerna exec --scope <包名> -- cd ./src

--stream

显示命令输出, 带包前缀

lerna exec --scope localPackage -- ls

--parallel

显示命令输出, 忽略排序

lerna exec --parallel localPageck -- ls

--no-bail

禁止非零退出

lerna exec --nobail ...

--no-prefix

禁止包前缀

lerna exec --no-prefix

--profile

生成性能分析文件

lerna exec --profile

--profile-localtion

生成并保存性能分析文件

lerna exec --profile --profile-location=logs/profile/ --

import

导入外部独立包, 例如我们之前为使用lerna 管理的独立npm包，导入到lerna项目包集合后，可以使用改目录导入相关 git 记录等

lerna import <包地址>

参数:

--faltten

lerna import ./package --flatten

--dest

根据 lerna.json 指定导入的目录

// lerna.json
{
  "packages": [
    "pakcages/*",
    "utils/*"
  ]
}
// 执行导入
lerna import ../out-pkg --dest=utils
// out-pkg 将被导入utils目录下

--preserve-commit

保留原git 提交者信息以及时间

lerna import ../out-pkg --preserve-commit

changed

显示下次将发布的包列表，一般是包版本发生变化

lerna changed

命令参数于 list 命令相同。

--json
--ndjson
-a --all
-l --long
-p --parseable
--toposort
--graph

diff

显示包修改内容, 类似 git diff

lerna diff

info

显示环境信息

lerna info

问题

发布时git add 失败

这里我在.gitignore 中忽略了，版本锁文件。 package-lock.json。造成git add 发生冲突

参考文档

深入 lerna 发包机制 —— lerna publish-技术圈
@lerna/version（翻译）
@lerna/publish（翻译）
深入 lerna 发包机制 —— lerna version