Custom tips (实验性功能)

Custom tips 允许您为 Rush 打印的命令行消息添加为您的特定单仓库量身定制的建议 (tips)。

以下是一个 custom tips 能够帮忙的例子：假设您的公司使用一个私有的 NPM registry，该注册表定期从上游的 npmjs.com 服务器同步最新的包版本。有时用户可能试图安装刚刚发布的版本，而该版本尚未同步，此时 rush update 可能会显示以下错误：

Progress: resolved 0, reused 1, downloaded 0, added 0
/users/example/code/my-repo/apps/my-app:
 ERR_PNPM_NO_MATCHING_VERSION  No matching version found for example-library@1.2.3

This error happened while installing a direct dependency of my-app

The latest release of example-library is "1.1.0".

此错误有些令人困惑，因为 npm 上的最新发布版本确实是 1.2.3，而错误是因为您公司私有的 NPM registry 同步的最新最新版本还在 1.1.0。如果您的团队为 monorepo 维护一个帮助热线（比如 oncall 群），您可能会经常收到关于这个错误的 on-call。这可以通过显示 custom tip 来避免。

配置 custom tip

上面的 ERR_PNPM_NO_MATCHING_VERSION 代码来自 PNPM。Rush 对应的提示 ID 是 TIP_PNPM_NO_MATCHING_VERSION。我们可以如下定义提示：

common/config/rush/custom-tips.json

/**
 * 这个配置文件允许仓库维护者配置与某些 Rush 消息一起打印的额外详细信息。更多文档可在
 * Rush 官方网站上找到：https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/custom-tips.schema.json",

  /**
   * 指定 Rush 要显示的 custom tips。
   */
  "customTips": [
    // {
    //   /**
    //    * (必须) 一个标识符，表示 Rush 可能打印的消息。
    //    * 如果打印了该消息，则将显示此 custom tip。
    //    * 请参阅 Rush 文档以获取可能的标识符的当前列表。
    //    */
    //   "tipId": "TIP_RUSH_INCONSISTENT_VERSIONS",
    //
    //   /**
    //    * (必须) 要为此提示显示的消息文本。
    //    */
    //   "message": "要获取额外的故障排除信息，请参阅此 wiki 文章：\n\nhttps://intranet.contoso.com/docs/pnpm-mismatch"
    // }
    {
      "tipId": "TIP_PNPM_NO_MATCHING_VERSION",
       "message": "PNPM 的这个“no matching version”的错误经常是由于新版本尚未同步到我们公司的内部 NPM registry所导致的。\n\n要获取故障排除指南，请查阅我们的团队 wiki：\n\nhttps://example.com/wiki/npm-syncing"
    }
  ]
}

如果您没有此文件，您可以使用 rush init 生成它。

随着这次更改，用户现在将在原始错误旁边看到 custom tip：

Progress: resolved 0, reused 1, downloaded 0, added 0
/users/example/code/my-repo/apps/my-app:
 ERR_PNPM_NO_MATCHING_VERSION  No matching version found for example-library@1.2.3

This error happened while installing a direct dependency of my-app

The latest release of example-library is "1.1.0".

| Custom Tip (TIP_PNPM_NO_MATCHING_VERSION)
|
| PNPM 的这个“no matching version found”的错误经常是由于新版本尚未同步到我们公司的内部 NPM registry 所导致的。
|
| 要获取故障排除指南，请查阅我们的团队 wiki：
|
| https://example.com/wiki/npm-syncing

请注意，Rush 用 | 前缀 custom tips，以将其与 Rush 软件的官方消息区分开。

贡献新的 tips

有没有你想自定义的 Rush 消息，但没有可用的 tipId？实现新的 tips 相对容易。代码位于 rush-lib/src/api/CustomTipsConfiguration.ts， 请随时创建拉取请求来提议新的 tips。

Custom tip 标识符

TIP_PNPM_INVALID_NODE_VERSION

对应于 PNPM 的 ERR_PNPM_INVALID_NODE_VERSION。

TIP_PNPM_MISMATCHED_RELEASE_CHANNEL

对应于 PNPM 的 ERR_PNPM_MISMATCHED_RELEASE_CHANNEL。

TIP_PNPM_NO_MATCHING_VERSION

对应于 PNPM 的 ERR_PNPM_NO_MATCHING_VERSION。

TIP_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE

对应于 PNPM 的 ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE。

TIP_PNPM_OUTDATED_LOCKFILE

对应于 PNPM 的 ERR_PNPM_OUTDATED_LOCKFILE。

TIP_PNPM_PEER_DEP_ISSUES

对应于 PNPM 的 ERR_PNPM_PEER_DEP_ISSUES。

TIP_PNPM_TARBALL_INTEGRITY

对应于 PNPM 的 ERR_PNPM_TARBALL_INTEGRITY。

TIP_PNPM_UNEXPECTED_STORE

对应于 PNPM 的 ERR_PNPM_UNEXPECTED_STORE。

TIP_RUSH_INCONSISTENT_VERSIONS

当项目有不一致的依赖版本时，此消息由 rush install 或 rush update 打印，前提是你的项目在 rush.json 中启用了 ensureConsistentVersions（我们也推荐如此）。

Rush 输出示例：

Found 5 mis-matching dependencies!

另请参阅

• custom-tips.json 文档