Node 环境配置说明

本文档基于 2026-08-18 实际检查与配置结果编写（当日已恢复 pnpm 官方 standalone 结构），所有路径均为本机真实路径。 目标：Node 生态全部统一放在 D 盘 D:\APP\Node 下。

---

一、npm 是什么，pnpm 是什么

npm（Node Package Manager）

• Node.js 官方自带的包管理器，安装 Node.js 时自动携带，无需单独安装。
• 作用：下载、安装、卸载、管理 JavaScript 包（依赖库、命令行工具等）。
• 核心命令：npm install（装依赖）、npm install -g <包>（装全局工具）、npm run（运行脚本）。
• 特点：生态最大、最通用，任何 Node 项目都能用。

pnpm（Performant npm）

• 另一款流行的包管理器，用来替代 npm 完成同样的工作，但更"聪明"。
• 三个核心优势：
• 省磁盘：所有包内容以"内容寻址"方式存进一个全局 store，多个项目共享同一份，不重复下载；
• 快：包通过硬链接/符号链接从 store 引入，不用反复拷贝；
• 隔离严格：项目的 node_modules 结构更规范，杜绝"幽灵依赖"（没声明却能用）问题。
• 核心命令与 npm 几乎一致：pnpm install、pnpm add -g、pnpm run，可无缝上手。
• pnpm 本身也需要 Node.js 环境，它不替代 Node，只替代 npm。

---

二、它们各自放在哪里

组件	位置	说明
Node.js 本体	D:\APP\Node	运行时，npm/pnpm 都靠它执行
npm 本体	随 Node.js 内置	无需单独安装
npm 全局安装目录（prefix）	D:\APP\Node\npm-global	npm 全局装的包都放这里
npm 缓存（cache）	D:\APP\Node\node-cache	npm 下载的包缓存
pnpm 命令入口	D:\APP\Node\pnpm\bin\pnpm.cmd	PATH 中的 %PNPM_HOME%\bin
pnpm 本体	D:\APP\Node\pnpm\global\v11\<hash>\node_modules\@pnpm\exe\pnpm.exe	pnpm 自身作为全局包（@pnpm/exe）装在内容仓库里，pnpm.cmd 只是转发它的 shim
pnpm store（包仓库）	D:\APP\Node\pnpm\store	pnpm 所有包内容的唯一仓库
pnpm 全局包目录	D:\APP\Node\pnpm\global	pnpm 全局安装的项目
pnpm 配置主目录（PNPM_HOME）	D:\APP\Node\pnpm	环境变量 PNPM_HOME 指向这里
镜像源	https://mirrors.tencent.com/npm/	npm 和 pnpm 共用的腾讯镜像

关于 global\v11 里的"数字文件夹"：里面只有两类东西——

• 带 -1a013c... 长尾巴的真实文件夹（如 66e0-...、5894-...）：每个全局包一个"全局项目"（66e0-... 是 pnpm 本体 @pnpm/exe，5894-... 是 cowsay）；
• 纯 64 位十六进制的符号链接（如 6032a739...、65d4af...）：指向上面真实文件夹的"稳定标识"，pnpm.cmd 引用链接名而非目录名，目录名变化时 shim 不用改。

真实包文件最终都躺在 store\v11 里，global\v11 只是指针（包括 pnpm 自身），所以这些 hash 不用理解，只需要知道链接指向哪里。

配置写入位置：

• npm 的配置写在 C:\Users\YWH18\.npmrc（prefix、cache、registry 三项）。
• pnpm 的 store-dir / global-bin-dir / global-dir 三项写在 pnpm 自己的全局配置文件里（不读 .npmrc）。

---

三、它们下载、安装的包会放到哪里

npm 的包去向

场景	包内容放哪	命令入口放哪
项目安装（npm install）	项目的 node_modules\ 目录	项目的 node_modules\.bin\
全局安装（npm install -g <包>）	D:\APP\Node\npm-global\node_modules\	D:\APP\Node\npm-global\<命令>.cmd（例如 eslint.cmd、vite.cmd）
下载缓存	D:\APP\Node\node-cache\_cacache\	—

pnpm 的包去向

场景	包内容放哪	命令入口放哪
项目安装（pnpm install）	包内容进 D:\APP\Node\pnpm\store\v11\（全局唯一一份），项目 node_modules\ 里是硬链接指向 store	项目的 node_modules\.bin\
全局安装（pnpm add -g <包>）	包内容进 store，全局项目记录在 D:\APP\Node\pnpm\global\v11\	D:\APP\Node\pnpm\bin\<命令>.cmd（例如 cowsay.CMD）
下载缓存	store 本身即内容仓库，另有无数据缓存	—

一句话总结：npm 全局的包"实打实"放在 npm-global 里；pnpm 的包全部集中在 pnpm\store 里，别处只有链接。

---

四、npm 和 pnpm 的相互关系

1. 共用同一套 Node.js 运行时：两者都只是 Node 之上的工具，执行任何脚本最终都靠 D:\APP\Node 里的 Node。

2. 安装方式独立：pnpm 本体通过官方安装脚本 install.ps1 安装到 D 盘（iwr https://get.pnpm.io/install.ps1 -useb | iex），不需要 npm 参与；两者可以独立安装、卸载，互不依赖。

3. 共享镜像源：registry=https://mirrors.tencent.com/npm/ 在 .npmrc 里，npm 和 pnpm 都读它，下载源一致。

4. 全局包互不干扰：

5. npm 全局工具 → D:\APP\Node\npm-global
6. pnpm 全局工具 → D:\APP\Node\pnpm\bin + pnpm\global

7. 两者各自管理，同一个包可以分别在两边各装一份，互不影响。

8. 命令入口分层：PATH 中 D:\APP\Node\pnpm\bin（pnpm 系命令）排在 D:\APP\Node\npm-global（npm 系命令）之前，同名命令优先命中 pnpm 侧。

9. 项目内通常二选一：一个项目用 npm 还是 pnpm 管理，取决于 package-lock.json（npm 的锁文件）还是 pnpm-lock.yaml（pnpm 的锁文件）。混用可能引起依赖结构混乱，不推荐。

---

五、npm、pnpx 和 pnpm 的关系

三者是"两个管理器 + 一个执行器"的关系：

命令	归属	是什么	典型用途
npm	npm 自带	包管理器	安装/卸载/管理包
npx	npm 自带	临时执行器	npx <包名> 临时下载并运行一个包，用完即走，不装进全局
pnpm	pnpm 自带	包管理器	与 npm 同类的装包工具
pnpx	pnpm 自带	临时执行器	pnpm 版的 npx，等价于 pnpm dlx

关系要点：

1. npm ↔ npx 是一对：npm 负责"装"，npx 负责"临时跑"。npx cowsay hi 会临时拉取 cowsay 运行，但不永久安装。
2. pnpm ↔ pnpx 是同样的关系：pnpx cowsay hi 等价于 pnpm dlx cowsay hi，临时执行，不污染全局。
3. npx 与 pnpx 的功能对等：都是"临时执行工具"，区别只是底层仓库不同——npx 临时下载的包走 npm 的缓存（node-cache），pnpx 走 pnpm 的 store（pnpm\store）。
4. npm 与 pnpm 功能对等：都可以装包、跑脚本、管理依赖；pnpm 在性能、磁盘占用、依赖隔离上更优，命令习惯上几乎兼容。

本机现状速查（2026-08-18 全项体检通过）：

• Node.js 版本：v24.19.0（本体在 D:\APP\Node\node.exe）；npm 版本：11.17.0；pnpm 版本：11.22.0
• npm 全局已装（7 个）：@colbymchenry/codegraph@0.9.6、@modelcontextprotocol/server-github@2025.4.8、eslint@10.3.0、playwright@1.60.0、tavily-mcp@0.2.21、typescript@6.0.3（提供 tsc/tsserver 命令）、vite@8.0.11（在 npm-global）
• pnpm 全局已装：@pnpm/exe@11.22.0（pnpm 本体）、cowsay@1.6.0（含 cowthink 命令）（在 pnpm\bin，包内容在 store）
• pnpm 本体：@pnpm/exe 11.22.0（官方 standalone，位于 pnpm\global\v11，由 pnpm.cmd 转发调用）
• 环境变量：PNPM_HOME=D:\APP\Node\pnpm（当前会话与注册表持久化一致）；PATH 中 D:\APP\Node\pnpm\bin 排在 D:\APP\Node\npm-global 之前
• store 状态：pnpm store status = "Packages in the store are untouched"（完整无损）
• 镜像连通：npm ping / pnpm ping 均正常响应（腾讯镜像）
• PowerShell 执行策略：各作用域均 Undefined（默认受限，新窗口跑 npm/pnpm 可能报 .ps1 被禁，可用 Set-ExecutionPolicy -Scope Process Bypass 临时放行）

---

附：注意事项（踩过的坑，记在这里）

1. pnpm store prune 会误删 pnpm 自身：prune 只按 store 引用记录判断，pnpm 本体不在记录里，会被当垃圾清掉。执行 prune 前后务必验证 pnpm --version。
2. pnpm 自更新：pnpm self-update 从 GitHub 下载，国内网络可能很慢（卡住可改用 npm 方式临时恢复）；更新的是 pnpm\global\v11 里的 @pnpm/exe 本体。
3. PowerShell 执行策略：新开的 PowerShell 窗口跑 npm/pnpm 若报 .ps1 被禁，先执行 Set-ExecutionPolicy -Scope Process Bypass（仅当前窗口有效）或 -Scope CurrentUser RemoteSigned（永久）。
4. 全局命令查找顺序：保证 D:\APP\Node\pnpm\bin 在 D:\APP\Node\npm-global 之前（当前已满足）。
5. 官方安装脚本依赖 GitHub：install.ps1 从 GitHub 下载 standalone 包，网络不通时会长时间卡在 "Downloading pnpm from GitHub..."（2026-08-18 改网络环境后已成功）。卡住时用 npm 方案临时恢复：npm install -g --prefix "D:\APP\Node\pnpm\bin" pnpm@11.22.0。

---

附：环境体检命令（一键检查）

下方命令块可整体多行复制，直接粘贴到 CMD 窗口运行，逐段执行。执行结果与各节"期望值"对照，全绿即环境健康。2026-08-18 实测全部通过。

REM ===== 一、版本与命令位置 =====
node --version
npm --version
pnpm --version
where node
where npm
where pnpm

REM ===== 二、npm 配置 =====
npm config get prefix
npm config get cache
npm config get registry
npm config list
type "C:\Users\YWH18\.npmrc"

REM ===== 三、pnpm 配置 =====
pnpm config list --location global
pnpm config get store-dir
pnpm config get global-bin-dir
pnpm config get global-dir
pnpm config get registry
pnpm store path
pnpm store status

REM ===== 四、环境变量 =====
echo %PNPM_HOME%
reg query "HKCU\Environment" /v PNPM_HOME
reg query "HKCU\Environment" /v Path

REM ===== 五、目录结构 =====
dir /b "D:\APP\Node\npm-global"
dir /b "D:\APP\Node\node-cache"
dir /b "D:\APP\Node\pnpm\bin"
dir /b "D:\APP\Node\pnpm\store\v11"
dir /b "D:\APP\Node\pnpm\global\v11"

REM ===== 六、链路与可用性 =====
type "D:\APP\Node\pnpm\bin\pnpm.cmd"
if exist "D:\APP\Node\pnpm\global\v11\66e0-1a013c1aa6e-db5c190e6ca65d13\node_modules\@pnpm\exe\pnpm.exe" (echo 本体存在) else (echo 本体不存在)
pnpm ls -g
npm ls -g --depth=0
cowsay hi
pnpx cowsay hi

REM ===== 七、死链接检查 =====
dir "D:\APP\Node\pnpm\store\v11\projects"

REM ===== 八、镜像连通 =====
npm ping
pnpm ping

REM ===== 九、PowerShell 执行策略（可选） =====
powershell -NoProfile -Command "Get-ExecutionPolicy -List"

期望值对照：

段	期望
一	node v24.x / npm 11.x / pnpm 11.22.0；where 三条都指向 D:\APP\Node 下
二	prefix=D:\APP\Node\npm-global、cache=D:\APP\Node\node-cache、registry=腾讯镜像
三	三项固化配置为 D:\APP\Node\pnpm\store / \bin / \global；store path=store\v11；store status="untouched"
四	PNPM_HOME=D:\APP\Node\pnpm（两条一致）；Path 中 pnpm\bin 在 npm-global 之前
五	npm-global 有 7 个包 shim；node-cache 有 _cacache；pnpm\bin 有 pnpm/pn/pnpx/pnx + cowsay/cowthink 且无 node_modules；store\v11 有 files/links/index.db/projects；global\v11 有 @pnpm/exe 与 cowsay 两个项目
六	pnpm.cmd 转发到 global\v11\...\@pnpm\exe\pnpm.exe；"本体存在"；cowsay 正常输出
七	projects 下所有 JUNCTION 指向存在的路径（无 D:\AI\pnpm\... 死链接）
八	均返回 PONG
九	各作用域 Undefined 属正常（默认受限），非异常

2026-08-18 状态

Microsoft Windows [Version 10.0.26200.8246]
(c) Microsoft Corporation. All rights reserved.

C:\Users\YWH18>node --version
v24.19.0

C:\Users\YWH18>npm --version
11.17.0

C:\Users\YWH18>pnpm --version
11.22.0

C:\Users\YWH18>where node
D:\APP\Node\node.exe

C:\Users\YWH18>where npm
D:\APP\Node\npm
D:\APP\Node\npm.cmd

C:\Users\YWH18>where pnpm
D:\APP\Node\pnpm\bin\pnpm
D:\APP\Node\pnpm\bin\pnpm.CMD

C:\Users\YWH18>npm config get prefix
D:\APP\Node\npm-global

C:\Users\YWH18>npm config get cache
D:\APP\Node\node-cache

C:\Users\YWH18>npm config get registry
https://mirrors.tencent.com/npm/

C:\Users\YWH18>npm config list
; "builtin" config from D:\APP\Node\node_modules\npm\npmrc

; prefix = "C:\\Users\\YWH18\\AppData\\Roaming\\npm" ; overridden by user

; "user" config from C:\Users\YWH18\.npmrc

cache = "D:\\APP\\Node\\node-cache"
prefix = "D:\\APP\\Node\\npm-global"
registry = "https://mirrors.tencent.com/npm/"

; node bin location = D:\APP\Node\node.exe
; node version = v24.19.0
; npm local prefix = C:\Users\YWH18
; npm version = 11.17.0
; cwd = C:\Users\YWH18
; HOME = C:\Users\YWH18
; Run `npm config ls -l` to show all defaults.

C:\Users\YWH18>type "C:\Users\YWH18\.npmrc"
prefix=D:\APP\Node\npm-global
cache=D:\APP\Node\node-cache
registry=https://mirrors.tencent.com/npm/

C:\Users\YWH18>pnpm config list --location global
{
  "@jsr:registry": "https://npm.jsr.io/",
  "globalBinDir": "D:\\APP\\Node\\pnpm\\bin",
  "globalDir": "D:\\APP\\Node\\pnpm\\global",
  "location": "global",
  "registry": "https://mirrors.tencent.com/npm/",
  "storeDir": "D:\\APP\\Node\\pnpm\\store",
  "userAgent": "pnpm/11.22.0 npm/? node/v26.0.0 win32 x64"
}

C:\Users\YWH18>pnpm config get store-dir
D:\APP\Node\pnpm\store

C:\Users\YWH18>pnpm config get global-bin-dir
D:\APP\Node\pnpm\bin

C:\Users\YWH18>pnpm config get global-dir
D:\APP\Node\pnpm\global

C:\Users\YWH18>pnpm config get registry
https://mirrors.tencent.com/npm/

C:\Users\YWH18>pnpm store path
D:\APP\Node\pnpm\store\v11

C:\Users\YWH18>pnpm store status
Packages in the store are untouched

C:\Users\YWH18>echo %PNPM_HOME%
D:\APP\Node\pnpm

C:\Users\YWH18>reg query "HKCU\Environment" /v PNPM_HOME

HKEY_CURRENT_USER\Environment
    PNPM_HOME    REG_SZ    D:\APP\Node\pnpm


C:\Users\YWH18>reg query "HKCU\Environment" /v Path

HKEY_CURRENT_USER\Environment
    Path    REG_EXPAND_SZ    %PNPM_HOME%\bin;D:\APP\Node\pnpm\bin;C:\Users\YWH18\AppData\Local\Microsoft\WindowsApps;D:\APP\Microsoft VS Code\bin;C:\Users\YWH18\.dotnet\tools;D:\APP\Node\npm-global;D:\AI\ClaudeCode;


C:\Users\YWH18>dir /b "D:\APP\Node\npm-global"
.browsers
codegraph
codegraph.cmd
codegraph.ps1
eslint
eslint.cmd
eslint.ps1
mcp-server-github
mcp-server-github.cmd
mcp-server-github.ps1
node_modules
playwright
playwright.cmd
playwright.ps1
tavily-mcp
tavily-mcp.cmd
tavily-mcp.ps1
tsc
tsc.cmd
tsc.ps1
tsserver
tsserver.cmd
tsserver.ps1
vite
vite.cmd
vite.ps1

C:\Users\YWH18>dir /b "D:\APP\Node\node-cache"
_cacache
_logs
_npx
_prebuilds
_update-notifier-last-checked

C:\Users\YWH18>dir /b "D:\APP\Node\pnpm\bin"
cowsay
cowsay.CMD
cowsay.ps1
cowthink
cowthink.CMD
cowthink.ps1
pn
pn.CMD
pn.ps1
pnpm
pnpm.CMD
pnpm.ps1
pnpx
pnpx.cmd
pnpx.ps1
pnx
pnx.cmd
pnx.ps1

C:\Users\YWH18>dir /b "D:\APP\Node\pnpm\store\v11"
.pnpm-needs-build-marker
files
index.db
links
projects

C:\Users\YWH18>dir /b "D:\APP\Node\pnpm\global\v11"
5894-1a01354629b-ba53555491f6d1ea
6032a739a7012101465789c02467d0128fd22adbfd6412cc896567e6d7e30062
65d4af063475f3d9411907b55d9f7019e45c50100513112c0e795efd093c96f0
66e0-1a013c1aa6e-db5c190e6ca65d13

C:\Users\YWH18>powershell -NoProfile -Command "Get-ExecutionPolicy -List"

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser       Undefined
 LocalMachine       Undefined



C:\Users\YWH18>type "D:\APP\Node\pnpm\bin\pnpm.cmd"
@SETLOCAL
@"%~dp0\..\global\v11\6032a739a7012101465789c02467d0128fd22adbfd6412cc896567e6d7e30062\node_modules\@pnpm\exe\pnpm.exe"   %*

C:\Users\YWH18>if exist "D:\APP\Node\pnpm\global\v11\66e0-1a013c1aa6e-db5c190e6ca65d13\node_modules\@pnpm\exe\pnpm.exe" (echo 本体存在) else (echo 本体不存在)
本体存在

C:\Users\YWH18>pnpm ls -g
Legend: production dependency, optional only, dev only

D:\APP\Node\pnpm\global\v11 (PRIVATE)
│
│   dependencies:
├── @pnpm/exe@11.22.0
└── cowsay@1.6.0

C:\Users\YWH18>npm ls -g --depth=0
D:\APP\Node\npm-global
+-- @colbymchenry/codegraph@0.9.6
+-- @modelcontextprotocol/server-github@2025.4.8
+-- eslint@10.3.0
+-- playwright@1.60.0
+-- tavily-mcp@0.2.21
+-- typescript@6.0.3
`-- vite@8.0.11


C:\Users\YWH18>cowsay hi
 ____
< hi >
 ----
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

C:\Users\YWH18>pnpx cowsay hi
Packages: +33
+++++++++++++++++++++++++++++++++
Progress: resolved 33, reused 33, downloaded 0, added 1, done
 ____
< hi >
 ----
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

C:\Users\YWH18>dir "D:\APP\Node\pnpm\store\v11\projects"
 Volume in drive D is 新加卷
 Volume Serial Number is 5C56-1229

 Directory of D:\APP\Node\pnpm\store\v11\projects

2026/08/18  15:43    <DIR>          .
2026/08/18  15:43    <DIR>          ..
2026/08/18  11:48    <DIR>          36a71d7cc72698d74c0c02c2be3fd924
2026/08/18  13:24    <JUNCTION>     46a34a5b964b203db5fb40d344f666f4 [D:\APP\Node\pnpm\global\v11\5894-1a01354629b-ba53555491f6d1ea]
2026/08/18  15:39    <JUNCTION>     56a213ef1986c6e908701c8143ee9b37 [C:\Users\YWH18]
2026/08/18  15:24    <JUNCTION>     5fbed461505d4fc6764b6b4bd5f89eb5 [D:\APP\Node\pnpm\global\v11\66e0-1a013c1aa6e-db5c190e6ca65d13]
2026/08/18  11:48    <DIR>          70320274f064f5e974f3cb21789dd70f
2026/08/18  13:18    <DIR>          891d9331de3284d892ea54bec0cb635e
2026/08/18  15:43    <JUNCTION>     cc425d03e668775decad68b6551f86a7 [C:\Users\YWH18\AppData\Local\pnpm-cache\dlx\718aa9664460f196723c6b9ed604661f\msycvd81-j6c]
               0 File(s)              0 bytes
               9 Dir(s)  213,590,171,648 bytes free

C:\Users\YWH18>npm ping
npm notice PING https://mirrors.tencent.com/npm/
npm notice PONG 210ms

C:\Users\YWH18>pnpm ping
PING https://mirrors.tencent.com/npm/
PONG 279ms

C:\Users\YWH18>