跳至主要内容
非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

故障排除

本文档记录了用户在使用 Lerna 过程中曾遇到的常见问题及其解决方案。

导入命令​

导入过程中出现缓冲区问题​

当尝试导入包含大量提交历史的仓库时，可能会遇到类似错误：

DeprecationWarning: Unhandled promise rejections are deprecated

或

Error: spawnSync /bin/sh ENOBUFS during ImportCommand.execute

解决方案：​

运行 lerna import 时添加 --max-buffer 标志并指定足够大的字节数。撰写本文时默认缓冲区大小为 10MB，请根据实际情况调整。

无法导入包含冲突解决的合并提交​

当导入包含需要冲突解决的合并提交的仓库时，导入命令会报错：

lerna ERR! execute Error: Command failed: git am -3
lerna ERR! execute error: Failed to merge in the changes.
lerna ERR! execute CONFLICT (content): Merge conflict in [file]

解决方案​

使用 --flatten 标志运行 lerna import，以"扁平化"模式导入历史记录，即将每个合并提交视为单个变更集。

Git 树存在未提交更改时失败​

当项目中存在未提交的更改时，你会收到 fatal: ambiguous argument 'HEAD': 错误。

解决方案​

在使用 lerna import 导入任何包之前，请确保提交 Lerna 项目中的所有更改。

发布命令​

固定模式下无法检测手动创建的 GitHub/GitHub Enterprise 标签​

GitHub 和 GitHub Enterprise 在通过网页界面创建版本时使用轻量级 Git 标签，而 Lerna 使用注解标签。

这会导致 Lerna 忽略通过 GitHub 网页界面手动发布并标记的历史版本。

例如发布历史如下：

  • v1.1.0 通过 lerna publish 发布并标记

  • v1.2.0 通过 GitHub 网页界面手动发布并标记

  • v1.2.1 通过 GitHub 网页界面手动发布并标记

此时运行 lerna publish 会检测 v1.1.0 而非 v1.2.1 作为最新发布标签。

具体影响取决于 lerna publish 的使用方式：

  • 发布提示将以 v1.1.0 为基础计算主版本/次版本/修订版本建议

  • 使用 --conventional-commits 标志时：

    • 会基于 v1.1.0 之后的所有提交（含 v1.2.0、v1.2.1 等）计算语义化版本增量
    • 生成的 CHANGELOG.md 文件会重复包含 v1.2.0、v1.2.1 等版本中已发布的提交记录

解决方案：​

尽可能使用 lerna publish 代替手动发布。

如需手动发布新版本，请使用 git tag -a -m <version> 命令而非 GitHub 网页界面。

现有轻量级标签可通过如下方式转换为注解标签：

GIT_AUTHOR_NAME="$(git show $1 --format=%aN -s)"
GIT_AUTHOR_EMAIL="$(git show $1 --format=%aE -s)"
GIT_AUTHOR_DATE="$(git show $1 --format=%aD -s)"
GIT_COMMITTER_NAME="$(git show $1 --format=%cN -s)"
GIT_COMMITTER_EMAIL="$(git show $1 --format=%cE -s)"
GIT_COMMITTER_DATE="$(git show $1 --format=%cD -s)"

git tag -a -m $1 -f $1 $1

git push --tags --force

更多细节请参阅此 Stackoverflow 帖子

发布到私有 npm 仓库（Artifactory、npm Enterprise 等）​

若 lerna publish 失败，请确保 package.json 中包含以下配置：

	"publishConfig": {
		"registry": "https://[registry-url]"
	}

你可能还需要在单个包的 .npmrc 文件中添加以下内容：

registry = https://[registry-url]
信息

无论 lerna.json 文件中设置的 npmClient 是什么，Lerna 始终使用 npm 工具来发布包。这意味着任何 yarn 或 pnpm 的配置都不会被检测到。为确保成功发布到私有注册表，请通过环境变量或 .npmrc 文件正确配置 npm。

Jest / Visual Studio Code 调试​

可以在 Lerna 管理的包中使用 Visual Studio Code 调试 Jest 测试。通过在 monorepo 的 <root>/.vscode/launch.json 文件中添加以下启动配置，即可实现带断点的调试功能。此示例针对位于 monorepo 中的单个包 my-package 启动 Jest 测试：

{
    "name": "Jest my-package",
    "type": "node",
    "request": "launch",
    "address": "localhost",
    "protocol": "inspector",
    "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/lerna",
    "runtimeArgs": [
        "exec",
        "--scope",
        "my-package",
        "--",
        "node"
    ],
    "args": [
        "${workspaceRoot}/node_modules/jest/bin/jest.js",
        "--runInBand",
        "--no-cache",
        "packages/my-package"
    ]
}

已在 Visual Studio Code v1.19.3 和 Jest v22.1.4 版本测试通过。