Skip to main content

故障排除

¥Troubleshooting

本文档包含我们的用户过去在使用 Lerna 时遇到的某些问题的解决方案。

¥This document contains solutions for certain issues our users encountered in the past while using Lerna.

导入命令​

¥Import Command

导入期间的缓冲区问题​

¥Buffer problems during import

当你尝试导入包含许多提交的存储库时，你可能会收到如下错误：

¥When you try to import a repository which has many commits in it there is a chance that you get an error such as:

DeprecationWarning: Unhandled promise rejections are deprecated

或者

¥or

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

解决方案：​

¥Solution:

使用 --max-buffer 标志运行 lerna import 并提供足够大的数字（以字节为单位）。在撰写本文时，基本默认值为 10MB，因此你应该记住这一点。

¥Run lerna import with the --max-buffer flag and provide a large enough number (in bytes). At the writing of this entry the underlying default is 10MB, so you should keep this in mind.

无法导入合并冲突提交​

¥Merge conflict commits cannot be imported

当你尝试导入包含需要解决冲突的合并提交的存储库时，导入命令失败并出现错误：

¥When you try to import a repository that contains merge commits that needed conflict resolutions, the import command fails with an error:

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]

解决方案​

¥Solution

使用 --flatten 标志运行 lerna import 以在 "flat" 模式下导入历史记录，即每次合并提交作为合并引入的单个更改。

¥Run lerna import with the --flatten flag to import the history in "flat" mode, i.e. with each merge commit as a single change the merge introduced.

当 git 树有未提交的更改时失败​

¥Failing when git tree has uncommitted changes

当当前项目有未提交的更改时，你将收到 fatal: ambiguous argument 'HEAD': 错误。

¥You will receive fatal: ambiguous argument 'HEAD': error, when the current project has uncommitted changes.

解决方案​

¥Solution

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

¥Make sure to commit all the changes you have in your lerna project, before importing any packages using lerna import.

发布命令​

¥Publish Command

使用 Github/Github Enterprise 发布不会检测固定模式下手动创建的标签​

¥Publish does not detect manually created tags in fixed mode with Github/Github Enterprise

当通过 网络用户界面 创建版本时，Github 和 Github Enterprise 使用轻量级 Git 标签，而 Lerna 使用带注释的标签。

¥Github and Github Enterprise use lightweight Git tags when a release is created through the web ui, while Lerna uses annotated tags.

这可能会导致 Lerna 忽略先前发布的已手动执行并使用 Github Web ui 标记的版本的问题。

¥This can cause an issue where Lerna will ignore previously published releases which have been manually performed and tagged with the Github web ui.

例如，如果发布历史记录如下：

¥For example if the publish history was as follows:

  • v1.1.0 已发布并标记为 lerna publish

    ¥v1.1.0 was published and tagged with lerna publish

  • v1.2.0 已手动发布并使用 Github Web ui 进行标记

    ¥v1.2.0 was manually published and tagged with the Github web ui

  • v1.2.1 已手动发布并使用 Github Web ui 进行标记

    ¥v1.2.1 was manually published and tagged with the Github web ui

现在运行 lerna publish 将检测 v1.1.0 而不是 v1.2.1 作为最后发布的标签。

¥Running lerna publish now would detect v1.1.0 instead of v1.2.1 as the last released tag.

这的含义取决于你对 lerna publish 的使用：

¥The implications of this depends on your usage of lerna publish:

  • 发布提示将使用 v1.1.0 作为主要/次要/补丁建议的基础。

    ¥The publish prompt would use v1.1.0 as the base for major/minor/patch suggestions.

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

    ¥When using the --conventional-commits flag:

    • 会建议基于 v1.1.0 以来的所有提交（包括 v1.2.0、v1.2.1 等的提交）进行 semver 增量

      ¥would suggest a semver increment based on all the commits since v1.1.0 (including commits from v1.2.0, v1.2.1 etc)

    • 生成的 CHANGELOG.md 文件将重复 v1.2.0、v1.2.1 等中已发布的所有提交

      ¥The generated CHANGELOG.md files will repeat all the commits that have already been released in v1.2.0, v1.2.1 etc

解决方案：​

¥Solution:

如果可能，请使用 lerna publish 而不是手动发布。

¥If possible, use lerna publish over manual releases.

对于新的手动版本，请使用 git tag -a -m <version> 而不是使用 Github Web UI。

¥For new manual releases, use git tag -a -m <version> instead of using the Github web ui.

对于现有的轻量级标签，可以使用如下方式将它们转换为带注释的标签：

¥For existing lightweight tags, they can be converted to an annotated tag using something like this:

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 帖子 了解更多详细信息

¥See this Stackoverflow post for more details

发布到私有 npm 注册表（Artifactory、npm Enterprise 等）​

¥Publishing to a private npm registry (Artifactory, npm Enterprise, etc)

如果 lerna publish 失败，请确保你的 package.json 具有以下内容：

¥If lerna publish is failing ensure you have the following your package.json:

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

你可能还需要将以下内容添加到各个软件包的 .npmrc 文件中：

¥You may also need to add the following to your .npmrc file on the individual package(s):

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

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

¥Lerna always uses npm tooling to publish packages, regardless of the npmClient set in the lerna.json file. This means that any yarn or pnpm configuration will not be detected. To ensure successful publishing to a private registry, make sure that npm is configured properly with environment variables or a .npmrc file.

Jest / Visual Studio 代码调试​

¥Jest / Visual Studio Code Debugging

可以使用 Visual Studio Code 在 Lerna 管理的包中调试 Jest 测试。使用断点调试适用于下面 monorepo 的 <root>/.vscode/launch.json 文件中的 vscode 启动配置。此示例为位于 monorepo 中的单个包 my-package 启动 Jest。

¥It is possible to debug Jest tests in a Lerna-managed package using Visual Studio Code. Debugging with breakpoints works with the vscode launch configuration below in the monorepo's <root>/.vscode/launch.json file. This example launches Jest for a single package my-package located in the monorepo.

{
    "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 进行测试。

¥Tested with Visual Studio Code v1.19.3 and Jest v22.1.4.