From df11ca0db69f7d235ab7f012d160df8982b3fd4a Mon Sep 17 00:00:00 2001
From: sheng <905537351@qq.com>
Date: Tue, 2 Jun 2026 14:42:33 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E7=8E=AF=E5=A2=83=E6=90=AD=E5=BB=BA=E6=96=87=E6=A1=A3=E5=B9=B6?=
 =?UTF-8?q?=E6=B7=BB=E5=8A=A0volta=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. 补充Windows下Volta安装后的生效方式说明
2. 完善不同环境下Node版本安装指引
3. 新增volta命令无法识别的问题排查方案
4. 在package.json中添加volta的node版本配置
---
 README.md    | 74 ++++++++++++++++++++++++++++++++++++++--------------
 package.json |  3 +++
 2 files changed, 58 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 52f6ba91..614ea4b2 100644
--- a/README.md
+++ b/README.md
@@ -30,10 +30,22 @@ Volta 会根据 `.node-version` 自动安装并切换到项目所需的 Node.js
 
 ```powershell
 winget install Volta.Volta
-# 重启终端后生效
-volta --version
 ```
 
+> `winget` 安装完成后，**当前终端窗口不会自动加载 Volta**。选择以下任一方式生效：
+>
+> **方式一（关闭重开）：** 关掉当前终端，重新打开一个 PowerShell / VS Code 终端。
+>
+> **方式二（不重启立即生效）：** 在当前终端执行：
+> ```powershell
+> $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
+> ```
+>
+> 生效后验证：
+> ```powershell
+> volta --version   # 应输出版本号（如 2.0.2）
+> ```
+
 **macOS / Linux：**
 
 ```bash
@@ -68,18 +80,20 @@ pnpm --version   # 应输出 10.33.0
 git clone <仓库地址>
 cd mes-ui
 
-# Volta 会在进入目录时自动检测 .node-version，
-# 提示你安装 Node.js 18.16.0（如尚未安装）
-node --version   # 确认输出 v18.16.0
+# Volta 检测到 .node-version 后，自动下载并安装 Node.js 18.16.0
+# 如果你本机没有这个版本，Volta 会提示 "Fetching node@18.16.0" —— 等它完成即可
+node --version   # 应输出 v18.16.0
 
-# 安装依赖（pnpm 读取 packageManager 字段确保版本一致）
+# 安装依赖
 pnpm install
 ```
 
-> `pnpm install` 会同时校验：
-> - Node.js 版本是否在 `engines.node` 范围内（`>=18.16.0 <19`）
-> - pnpm 版本是否在 `engines.pnpm` 范围内（`>=10.33.0 <11`）
-> - 如果版本不匹配，`.npmrc` 中 `engine-strict=true` 会使安装直接失败，避免环境不一致问题。
+> **没有安装 Node 18.16.0 怎么办？**  
+> **Volta 用户**：无需手动操作。进入项目目录时 Volta 会自动检测 `.node-version`，如果本机缺这个版本，它会**自动下载安装**，你只需等待几秒终端提示完成即可。  
+> **nvm 用户**：执行 `nvm install 18.16.0 && nvm use 18.16.0`。  
+> **手动安装**：去 [nodejs.org](https://nodejs.org/) 下载 Node.js 18.16.0 安装包。  
+>
+> 装完后建议运行 `node --version` 确认输出 `v18.16.0`，否则 `pnpm install` 会因为 `engine-strict=true` 直接报错拒绝安装。
 
 ### 第四步：配置环境变量
 
@@ -288,18 +302,26 @@ mes-ui/
 
 ### Q1：`pnpm install` 报错 "Unsupported engine"
 
-Node.js 或 pnpm 版本不在 `engines` 范围内。解决：
+> 意思：本机 Node.js 或 pnpm 版本不在项目规定范围内，install 被阻断。
+
+**先排查版本：**
 
 ```bash
-# 检查版本
-node --version   # 必须为 18.16.x
-pnpm --version   # 必须为 10.33.x
-
-# 使用 Volta 自动切换
-volta install node@18.16.0
-volta install pnpm@10.33.0
+node --version   # 项目要求 >=18.16.0 <19
+pnpm --version   # 项目要求 >=10.33.0 <11
 ```
 
+**谁把版本不对：**
+
+| 情景 | 解决办法 |
+| --- | --- |
+| **用 Volta**（推荐） | `volta install node@18.16.0` + `volta install pnpm@10.33.0`，进入项目目录自动生效 |
+| **用 nvm** | `nvm install 18.16.0 && nvm use 18.16.0`，再 `npm install -g pnpm@10.33.0` |
+| **手动安装** | 去 [nodejs.org](https://nodejs.org/) 下载 18.16.0，再 `npm install -g pnpm@10.33.0` |
+| **已有正确版本但切换不生效** | 重新打开终端，确保 `volta` / `nvm` 已正确加载 |
+
+> 版本验证通过后，重新执行 `pnpm install`。
+
 ### Q2：启动后页面报跨域错误
 
 在 `.env.development.local` 中确认 `VUE_APP_API` 指向正确的后台地址，且后台已开启 CORS。
@@ -312,7 +334,21 @@ volta install pnpm@10.33.0
 PORT=8081
 ```
 
-### Q4：依赖安装慢
+### Q4：`volta` 命令无法识别 / "无法将 volta 项识别为 cmdlet"
+
+> 原因：`winget install Volta.Volta` 不会自动刷新当前终端的 PATH 缓存。
+
+**解决办法二选一：**
+
+```powershell
+# 方案 A：关掉当前终端，重新打开一个（推荐，最简单）
+# 方案 B：在当前终端执行以下命令立即生效，免重启
+$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
+```
+
+> 生效后 `volta --version` 应输出版本号。
+
+### Q5：依赖安装慢
 
 pnpm 默认使用 npm registry。如需加速，可配置镜像：
 
diff --git a/package.json b/package.json
index cd2b4c24..3e7f4869 100644
--- a/package.json
+++ b/package.json
@@ -94,5 +94,8 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/d2-projects/d2-admin.git"
+  },
+  "volta": {
+    "node": "18.16.0"
   }
 }