@umacloud/knowledge 1.0.23 → 1.0.25

package/development/01-standards/windows-node-cli-invocation.md

@@ -0,0 +1,48 @@
+---
+id: windows-node-cli-invocation
+title: Windows 上调用 node 工具链的正确方式（绕开 .ps1 shim 与执行策略闸门）
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [windows, powershell, cmd, execution-policy, npm, npx, pnpm, yarn, node-gyp, ps1-shim, environment-gate, no-retry, 执行策略, 环境闸门, 禁止运行脚本, 商业级]
+quality_score: 95
+last_updated: 2026-07-02
+---
+# Windows 上调用 node 工具链的正确方式（.ps1 shim 与执行策略闸门）
+
+> 这条规范修的是一个高频死循环：在 Windows 上用 PowerShell 跑 `npm i` / `npx …`（例如 `powershell.exe -Command 'npm i'`），报「无法加载文件 …\npm.ps1，因为在此系统上禁止运行脚本」（英文环境为 "npm.ps1 cannot be loaded because running scripts is disabled on this system"，附带 about_Execution_Policies / PSSecurityException / UnauthorizedAccess），然后**原样重试同一条命令**——重试多少次都以同样的方式失败。
+> 核心结论：**Windows 上的 node 生态 CLI 一律走 cmd 调用（`cmd /c npm …`），不要经 PowerShell 的 `-Command 'npm …'`。** 执行策略报错是**环境闸门，不是偶发失败**：命令本身不变，永远不可能成功；正确动作是**换调用方式**，不是重试。
+
+## 1. 为什么会报「禁止运行脚本」
+
+- Windows 上的 npm/npx/pnpm/yarn 等 CLI 装出来是**三份 shim**：`npm`（POSIX shell 脚本）、`npm.cmd`（cmd 批处理）、`npm.ps1`（PowerShell 脚本）。
+- **PowerShell 里直接敲 `npm`，命令解析优先命中 `npm.ps1`**。而 Windows 默认的执行策略（Restricted）禁止运行任何 .ps1 脚本，于是 shim 本身就被拦下——报「无法加载文件 …npm.ps1，因为在此系统上禁止运行脚本」/ "cannot be loaded because running scripts is disabled on this system"。
+- 也就是说：**不是 npm 坏了、不是网络问题、不是依赖问题**，是"经 PowerShell 调用"这个方式本身撞上了机器的安全设置。npx / pnpm / yarn / node-gyp 全部同理（各有对应的 `.ps1` shim）。
+
+## 2. 铁律：换调用方式，绕开 .ps1 shim
+
+- **首选：走 cmd，让解析命中 `.cmd` shim**（cmd 不受 PowerShell 执行策略约束）：
+  - `cmd /c npm install`
+  - `cmd /c npx create-vite@latest my-app`
+  - `cmd /c pnpm install` / `cmd /c yarn build`（node-gyp 等同理）
+- **等价做法：显式调用 `.cmd` shim**，跳过解析歧义：
+  - `npm.cmd install` / `npx.cmd vitest run`
+- 自动化脚本、子进程调用同样适用：spawn 外部命令时指定 `npm.cmd`（或经 `cmd /c`），不要把裸 `npm` 交给 PowerShell 去解析。
+- **兜底（仅限单次、确需运行某个 .ps1 时）**：`powershell -ExecutionPolicy Bypass -File <script>.ps1`——只影响这一次调用，不落盘、不改机器设置。
+- **绝不要**为了跑过 npm 去改机器的执行策略（`Set-ExecutionPolicy …`）：那是用户的安全设置，不归本次任务动；改它属于扩大爆炸半径的修法。
+
+## 3. 判断准则：环境闸门 ≠ 偶发失败
+
+- 执行策略拦截是**确定性的**：同一条命令在同一台机器上，第 1 次失败和第 100 次失败一模一样。看到「禁止运行脚本」/ "running scripts is disabled"，**唯一正确的下一步是改命令**（换成 `cmd /c …` 或 `.cmd` shim），而不是：
+  - 原样重试同一条命令（永远不会成功）；
+  - 当成网络/依赖问题去清缓存、换源、重装；
+  - 去改用户机器的执行策略。
+- 通用推论：凡是**环境闸门类**报错（权限策略、缺工具链、系统设置拦截），重试都无意义——失败原因不随时间变化，**必须先改变命令或环境，再执行**。这与超时、网络抖动等**偶发类**失败（重试有意义）是两类问题，归类错了就会陷入重试死循环。
+
+## 4. 反模式（不要这样做）
+
+- `powershell.exe -Command 'npm i'`——经 PowerShell 解析裸 `npm`，命中被拦的 `npm.ps1` shim。
+- 报「禁止运行脚本」后原样重试同一条命令，一次、两次、N 次。
+- 把执行策略报错当成 npm/网络故障，去 `npm cache clean` / 换 registry / 删 node_modules 重装。
+- 用 `Set-ExecutionPolicy RemoteSigned/Unrestricted` 改机器策略来"修"一次 npm 调用。
+- 子进程/脚本里 spawn 裸 `npm` 并交给 PowerShell 宿主解析，而不是显式 `npm.cmd` 或 `cmd /c npm …`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umacloud/knowledge",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "UmaDev curated engineering knowledge corpus (standards, methodologies, expert playbooks, design systems, miniprogram/uniapp guides). Platform-independent data shipped once so npm users get the full KB offline.",
   "license": "MIT",
   "repository": { "type": "git", "url": "https://github.com/umacloud/umadev.git" },