docs: add check version (#3949)

* feat: add check version * docs: update check doc * docs: update check doc * docs: update check doc
midwayjs · Jul 12, 2024 · 1a996b6 · 1a996b6
1 parent 115ee35
commit 1a996b6
Show file tree

Hide file tree

Showing 7 changed files with 423 additions and 56 deletions.
diff --git a/site/blog/2024-05-07-release-3.16.md b/site/blog/2024-05-07-release-3.16.md
@@ -153,4 +153,4 @@ class Photo {
 * 修复了一个健康检查服务丢失 this 的问题
 * 参数装饰器增加了一个当前实例的参数
 
-以及一大批依赖进行了更新，可以参考我们的 [ChangeLog](https://midwayjs.org/changelog/v3.15.0)。
+以及一大批依赖进行了更新，可以参考我们的 [ChangeLog](https://midwayjs.org/changelog/v3.15.0)。
diff --git a/site/blog/2024-07-12-mwtsc-check.md b/site/blog/2024-07-12-mwtsc-check.md
@@ -0,0 +1,34 @@
+---
+slug: mwtsc-check
+title: mwtsc 增加版本检查
+authors: [harry]
+tags: [mwtsc]
+
+
+
+---
+
+由于 Midway 版本发布规则，`@midwayjs/core` 和组件有着版本对应关系，即低版本的 `@midwayjs/core` 无法使用高版本的组件。
+
+比如 `@midwayjs/[email protected]` 可能使用了高版本的 API，是无法在 `@midwayjs/[email protected]` 版本上执行的。
+
+由于 npm 等包管理的特性，包安装时不存在联系，`npm i @midwayjs/axios` 时往往只会安装组件最新的版本，非常容易造成兼容性问题。
+
+为此我们提供了 `npx midway-version` 命令，可以快速检查版本之间的兼容性错误。
+
+在推行一阵子之后，我们发现很少有用户主动去执行这样的指令，只会在出错时被动执行，再加上锁包和不锁包的复杂场景，会出现一些很难复现和排查的现象。
+
+为了降低复杂性，在 mwtsc 新版本的启动阶段，我们也加入了检查代码。
+
+![](https://img.alicdn.com/imgextra/i3/O1CN01ZHQcs51tDb5HrSviC_!!6000000005868-2-tps-1550-420.png)
+
+如果出现不兼容的版本，工具会进行提示。
+
+此外，新增的 `npx midway-version -m` 指令可以让固化版本的用户也享受到更新工具。
+
+和之前的 `-u` 指令不同，`-m` 会使用当前的 `@midwayjs/core` 版本，更新组件到最兼容的版本，而不是最新版本。
+
+结合 `mwtsc` 和 `midway-version` 工具，可以更简单的管理版本，如有问题可以反馈给我们改进。
+
+
+
diff --git a/site/docs/sidebars.json b/site/docs/sidebars.json
@@ -97,58 +97,6 @@
         ]
       ]
     },
-    {
-      "type": "category",
-      "label": "一体化",
-      "collapsed": true,
-      "collapsible": true,
-      "items": [
-        {
-          "type": "doc",
-          "id": "hooks/intro",
-          "label": "介绍"
-        },
-        {
-          "type": "category",
-          "label": "基础功能",
-          "collapsed": false,
-          "collapsible": false,
-          "items": [
-            "hooks/api",
-            "hooks/builtin-hooks",
-            "hooks/validate",
-            "hooks/middleware",
-            "hooks/cors",
-            "hooks/component",
-            "hooks/prisma",
-            "hooks/test",
-            "hooks/config",
-            "hooks/file-route",
-            "hooks/safe",
-            "hooks/upload"
-          ]
-        },
-        {
-          "type": "category",
-          "label": "一体化",
-          "collapsed": false,
-          "collapsible": false,
-          "items": [
-            "hooks/fullstack",
-            "hooks/client"
-          ]
-        },
-        {
-          "type": "category",
-          "label": "进阶",
-          "collapsed": false,
-          "collapsible": false,
-          "items": [
-            "hooks/deploy"
-          ]
-        }
-      ]
-    },
     {
       "type": "category",
       "label": "开发工具",
@@ -157,6 +105,7 @@
       "items": [
         "tool/create_midway",
         "tool/mwtsc",
+        "tool/version_check",
         "tool/mwts",
         "tool/luckyeye",
         "tool/egg-ts-helper"
@@ -196,7 +145,59 @@
       "collapsible": true,
       "items": [
         "logger",
-        "tool/cli"
+        "tool/cli",
+        {
+          "type": "category",
+          "label": "一体化",
+          "collapsed": true,
+          "collapsible": true,
+          "items": [
+            {
+              "type": "doc",
+              "id": "hooks/intro",
+              "label": "介绍"
+            },
+            {
+              "type": "category",
+              "label": "基础功能",
+              "collapsed": false,
+              "collapsible": false,
+              "items": [
+                "hooks/api",
+                "hooks/builtin-hooks",
+                "hooks/validate",
+                "hooks/middleware",
+                "hooks/cors",
+                "hooks/component",
+                "hooks/prisma",
+                "hooks/test",
+                "hooks/config",
+                "hooks/file-route",
+                "hooks/safe",
+                "hooks/upload"
+              ]
+            },
+            {
+              "type": "category",
+              "label": "一体化",
+              "collapsed": false,
+              "collapsible": false,
+              "items": [
+                "hooks/fullstack",
+                "hooks/client"
+              ]
+            },
+            {
+              "type": "category",
+              "label": "进阶",
+              "collapsed": false,
+              "collapsible": false,
+              "items": [
+                "hooks/deploy"
+              ]
+            }
+          ]
+        }
       ]
     }
   ],

diff --git a/site/docs/tool/luckyeye.md b/site/docs/tool/luckyeye.md
@@ -1,4 +1,4 @@
-# 检查工具
+# 规则检查工具
 
 Midway 为常见的错误提供了一些检查工具，以方便用户快速排错。`@midwayjs/luckyeye` 包提供了一些基础的检查规则，配合 Midway 新版本可以快速排查问题。
 

diff --git a/site/docs/tool/version_check.md b/site/docs/tool/version_check.md
@@ -0,0 +1,168 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# 版本检查工具
+
+由于依赖安装版本的不确定性，Midway 提供了 `midway-version` 这一版本检查工具，可以快速检查版本之间的兼容性错误。
+
+
+
+## 检查兼容性
+
+你可以使用下面的命令在项目根目录执行进行检查。
+
+以下命令会检查 `node_modules` 中实际安装的版本，而非 `package.json` 中写的版本。
+
+<Tabs groupId="midway-version">
+
+<TabItem value="npm" label="npm">
+
+```bash
+$ npx midway-version@latest
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+$ pnpx midway-version@latest
+```
+
+</TabItem>
+
+<TabItem value="yarn" label="yarn">
+
+```bash
+$ yarn add midway-version@latest
+$ yarn midway-version
+```
+
+</TabItem>
+
+</Tabs>
+
+
+
+## 升级到最新版本
+
+你可以使用下面的命令在项目根目录执行进行升级。
+
+`-u` 参数会检查 midway 所有模块，根据 `node_modules` 中实际安装的版本以及 `package.json` 中编写的版本，将其升级到 `最新` 版本。
+
+如当前安装的组件版本为 `3.16.2`，最新版本为 `3.18.0` ，则会提示升级到 `3.18.0`。
+
+在使用  `-u -w` 参数时：
+
+* 更新 `package.json` 的版本，保留前缀写法，比如 `^3.16.0` 会变为 `^3.18.0`
+* 将 `3.18.0` 版本写入到锁文件（如有）
+
+<Tabs groupId="midway-version">
+
+<TabItem value="npm" label="npm">
+
+```bash
+$ npx midway-version@latest -u
+```
+
+输出确认无误后，可以使用 `-w` 参数写入 `package.json` 和 `package-lock.json` 文件（如有）。
+
+```bash
+$ npx midway-version@latest -u -w
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+$ pnpx midway-version@latest -u
+```
+
+输出确认无误后，可以使用 `-w` 参数写入 `package.json` 和 `pnpm-lock.yaml` 文件（如有）。
+
+```bash
+$ pnpx midway-version@latest -u -w
+```
+
+</TabItem>
+
+<TabItem value="yarn" label="yarn">
+
+```bash
+$ yarn add midway-version@latest
+$ yarn midway-version -u
+```
+
+输出确认无误后，可以使用 `-w` 参数写入 `package.json` 和 `yarn.lock` 文件（如有）。
+
+```bash
+$ yarn midway-version -u -w
+```
+
+</TabItem>
+
+</Tabs>
+
+
+
+## 升级到可兼容的最新版本
+
+`-m` 参数会检查 midway 所有模块，根据 `node_modules` 中实际安装的版本以及 `package.json` 中编写的版本，将其升级到 `最新的兼容` 版本。
+
+如当前安装的组件版本为 `3.16.0`，最新版本为 `3.18.0` ，兼容版本为 `3.16.1` 和 `3.16.2`，则会提示升级到 `3.16.2`。
+
+一般使用 `-m` 参数的场景为固化低版本，检查错误的组件版本，所以策略和 `-u` 有所不同。
+
+在使用 `-m -w` 参数时：
+
+* 更新 `package.json` 的版本
+  * 如果有锁文件，将会保留前缀，比如 `^3.16.0` 会变为 `^3.16.2`
+  * 如果没有锁文件，将会移除前缀，固定版本，比如 `^3.16.0` 会变为 `3.16.2`
+
+* 将 `3.16.2` 版本写入到锁文件（如有）
+
+<Tabs groupId="midway-version">
+
+<TabItem value="npm" label="npm">
+
+```bash
+$ npx midway-version@latest -m
+```
+
+输出确认无误后，可以使用 `-w` 参数写入 `package.json` 和 `package-lock.json` 文件（如有）。
+
+```bash
+$ npx midway-version@latest -m -w
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+$ pnpx midway-version@latest -m
+```
+
+输出确认无误后，可以使用 `-w` 参数写入 `package.json` 和 `pnpm-lock.yaml` 文件（如有）。
+
+```bash
+$ pnpx midway-version@latest -m -w
+```
+
+</TabItem>
+
+<TabItem value="yarn" label="yarn">
+
+```bash
+$ yarn add midway-version@latest
+$ yarn midway-version -m
+```
+
+输出确认无误后，可以使用 `-w` 参数写入 `package.json` 和 `yarn.lock` 文件（如有）。
+
+```bash
+$ yarn midway-version -m -w
+```
+
+</TabItem>
+
+</Tabs>
+
diff --git a/site/i18n/en/docusaurus-plugin-content-docs/current/tool/luckyeye.md b/site/i18n/en/docusaurus-plugin-content-docs/current/tool/luckyeye.md
@@ -1,4 +1,4 @@
-# Check tool
+# Rule check tool
 
 Midway provides some checking tools for common errors to facilitate users to quickly debug them. The `@midwayjs/luckyeye` package provides some basic inspection rules, which can quickly troubleshoot problems with the new version of Midway.