跳转至

Node 使用与维护

一句话总结：环境装好之后的日常——装包命令速查（npm / pnpm / yarn / npx）、镜像源、维护与清理（删除项目、回收磁盘空间、卸载）、注意事项。

本文档基于 2026-10-03 重装后全机实测，所有路径均为本机真实路径。

📎 配套文档：《Node 安装与配置》—— Node/npm/pnpm 的安装、路径配置、D 盘八个文件夹的职责、pnpm 省磁盘机制都在那边。本文档中标注 《Node 安装与配置》7.x 的引用请到该文档查阅。

一、npm 装包

1
2
3
4
5
6
7
npm install                 # 装 package.json 里声明的全部依赖
npm i lodash                # 装一个包并写入 dependencies
npm i -D vitest             # 开发依赖（devDependencies）
npm i -g pnpm               # 全局安装
npm uninstall lodash        # 卸载
npm update                  # 升级
npm ls                      # 查看已装

常用参数

参数 简写 作用 例子
--save-dev -D 装到开发依赖 npm i -D vitest
--global -g 全局安装 npm i -g pnpm
--save-exact -E 锁定精确版本 npm i -E lodash@4.17.21
--registry 无 临时指定镜像源 npm i --registry=https://registry.npmmirror.com
--no-save 无 只装不写入 package.json npm i --no-save puppeteer

版本号语法

1
2
3
4
5
6
npm i lodash          # 最新稳定版
npm i lodash@4.17.21  # 精确版本
npm i lodash@^4       # 4.x 最新
npm i lodash@~4.17    # 4.17.x
npm i lodash@latest   # 明确要最新版
npm i lodash@next     # 预发布版（beta/rc）

^4.17.21 表示 ">=4.17.21 且 <5.0.0"；~4.17.21 表示 ">=4.17.21 且 <4.18.0"。生产想完全锁死用 -E。

二、pnpm 装包

1
2
3
4
5
6
7
8
pnpm install                # 安装全部依赖
pnpm add lodash             # 添加依赖（等价 npm i）
pnpm add -D vitest          # 开发依赖
pnpm add -g http-server     # 全局安装
pnpm remove lodash          # 卸载
pnpm update                 # 升级
pnpm list                   # 查看已装
pnpm dlx tsx a.ts           # 临时执行

与 npm 的关键差异

对比项 npm pnpm
磁盘占用 每个项目各存一份 全局 store 一份，项目里硬链接，巨省空间
安装速度 较慢 快，依赖复用
依赖隔离 node_modules 平铺，可能幽灵依赖 严格隔离，装不到的包就真的没有
本机 store — D:\APP\Node\pnpm_store

本机 pnpm store 缓存目录已指向 D 盘，避免了旧版本往 C 盘写 dlx 缓存的问题。

三、yarn（老牌，已边缘化）

1
2
3
4
yarn add lodash          # 添加依赖
yarn add -D vitest       # 开发依赖
yarn global add cowsay   # 全局
yarn remove lodash       # 卸载

新项目不建议再入坑 yarn classic（维护停滞），yarn berry（PnP 模式）又和生态有摩擦。npm 或 pnpm 二选一即可。

四、npx / pnpx：临时执行，不装进任何项目

不是安装命令，是"临时拉取并执行"——没装的 CLI 想用一次，用它最合适。

1
2
3
4
5
npx @deepseek-ai/dsh web             # 临时拉取并执行
npx -y @deepseek-ai/dsh web          # -y 跳过"是否安装"确认
npx tsx@4.19.0 script.ts             # 指定版本执行
npx tsc --version                    # 执行项目本地已装的包
npx -y @deepseek-ai/dsh@latest web   # 强制用最新版（不吃缓存）
要点 说明
缓存位置 npm cache 的 _npx\<hash>\（本机 D:\APP\Node\node_cache\_npx）
缓存命中条件 包名 + 版本完全一致；想更新须显式 @latest 或清缓存
与全局安装的区别 npx 用完即走不污染全局；要反复用、想敲短命令才值得 -g
pnpm 版 pnpx <包>＝pnpm dlx <包>，走 pnpm 的缓存体系

⚠️ pnpm add -g <包> --dry-run 不支持（实测报 unexpected argument '--dry-run'）。--dry-run 只在项目目录下的 pnpm install --dry-run 可用。

五、速查总表

想干什么 npm pnpm
装全部依赖 npm install pnpm install
装一个包 npm i lodash pnpm add lodash
装开发依赖 npm i -D vitest pnpm add -D vitest
全局装 npm i -g tsx pnpm add -g tsx
精确版本 npm i -E lodash@4.17.21 pnpm add -E lodash@4.17.21
卸载 npm uninstall lodash pnpm remove lodash
升级 npm update pnpm update
看装了啥 npm ls pnpm list
临时执行 npx tsx a.ts pnpm dlx tsx a.ts

真实场景

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# 1. 新项目初始化 + 装依赖
npm init -y && npm install
pnpm init && pnpm install

# 2. 后端框架
pnpm add express

# 3. 前端脚手架（开发依赖）
pnpm add -D vite @vitejs/plugin-react

# 4. 命令行工具，全局用
npm i -g pnpm

# 5. 临时用一次，不想装
npx -y degit user/repo my-project

# 6. 日常启动 DSH（本机已验证链路）
npx @deepseek-ai/dsh web

实测 pnpm init 生成的 package.json 会自动带上 "packageManager": "pnpm@12.8.1"、devEngines 和 "type": "module"，这是 pnpm 12 的新行为，用于锁定包管理器、防止队友误用 npm。

最该记住的三条

  1. 日常装包用 pnpm（快、省空间），命令是 pnpm add，不是 npm i。
  2. 想临时跑一次不安装，用 npx / pnpx，别 npm i -g。
  3. 全局装之前问一句：这工具我会反复用、想在任意目录敲短命令吗？是 → -g；否 → npx。

六、镜像源配置（本机已配腾讯云）

本机现状（2026-10-03 实测）：npm 与 pnpm 都已指向腾讯云镜像

1
https://mirrors.cloud.tencent.com/npm/

npm ping 实测返回 PONG 497ms，连通正常。

6.1 配置命令（两处都要改）

1
2
3
4
5
REM ① npm —— 写进 C:\Users\YWH18\.npmrc
npm config set registry https://mirrors.cloud.tencent.com/npm/

REM ② pnpm —— 写进 pnpm 自己的 auth.ini
pnpm config set registry https://mirrors.cloud.tencent.com/npm/

⚠️ 必须分别执行两条。pnpm 虽然会顺带读 .npmrc，但 pnpm config set registry 会把值固化进自己的 auth.ini，两处保持一致才最稳妥。 只改 .npmrc → pnpm 可能读到也可能读不到（取决于版本与作用域）；只改 pnpm → npm 完全不受影响。

6.2 其他可选镜像

1
2
3
4
5
REM 腾讯云镜像（本机采用）
https://mirrors.cloud.tencent.com/npm/

REM 淘宝镜像
https://registry.npmmirror.com/

⚠️ 注意区分两个腾讯域名：旧资料里常见的 https://mirrors.tencent.com/npm/ 是老的公网镜像；本机用的是腾讯云域名 https://mirrors.cloud.tencent.com/npm/。两者都是腾讯的，都能用，但建议全机统一写同一个，免得以后排查时混淆。

6.3 验证

1
2
3
4
npm config get registry     REM 应输出腾讯云镜像
pnpm config get registry    REM 应输出同一地址
npm ping                    REM 应返回 PONG
pnpm ping                   REM 应返回 PONG

6.4 关于 registry 的两个小知识

  1. pnpm config list 里的 registries 块是 pnpm 12 的新格式，会把默认源按作用域列出来（@jsr → jsr.io、@ → 当前 registry、gh → GitHub Packages 等）。看到 "scopes": ["@"] 指向腾讯云是正常现象，表示作用域包默认也走腾讯云。
  2. npm doctor 若提示"registry 不是官方源"：那是 doctor 只认官方源的误报，本机是故意配的腾讯云镜像，忽略即可。

七、维护与清理

7.1 日常维护命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
REM 更新 pnpm 本体（本机由 npm 安装，两种方式都可行）
npm update -g pnpm        REM 与当前安装方式一致，推荐
pnpm self-update          REM pnpm 官方方式（未在本机此安装形态下实测）

REM 更新全部 pnpm 全局包
pnpm update -g
pnpm outdated -g

REM 查看全局装了什么
pnpm ls -g
pnpm bin -g
npm ls -g --depth=0

REM npm 官方自检
npm doctor

npm doctor 里的 "Use newer npm/node version" 是版本建议、"registry 不是官方源"是镜像误报，都不是错误，理由详见 6.4。

7.2 清理分级

一级：零风险，随时可做

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
REM 1. npm 缓存校验（只报告，不改动）
npm cache verify

REM 2. npm 缓存清空（仅在磁盘紧张时做，清了下次装包要重新下载）
npm cache clean --force

REM 3. pnpm 的 registry 元数据缓存
pnpm cache prune

REM 4. pnpm 运行时锁 / 状态目录（删了会自动重建；跑着 pnpm 时别删）
rmdir /s /q "C:\Users\YWH18\AppData\Local\pnpm-store-operation-locks"

二级：需谨慎

1
2
3
4
REM pnpm store prune —— 清理 store 中未被引用的包
pnpm --version          REM ① 清理前记录版本号
pnpm store prune        REM ② 执行
pnpm --version          REM ③ 立刻验证

旧版本 pnpm 曾把本体也放 store 里，导致 store prune 可能误删 pnpm 自身。本次重装后 pnpm 由 npm 装在 node_global，与 pnpm store 无引用关系，理论上不再受影响——但这条命令本身没什么必要，store status 显示 untouched、磁盘也不紧张时就别跑它。

三级：禁止操作

禁止动作 原因
直接删 D:\APP\Node\pnpm_store 的子目录 只删 files/ 留下 index.db，索引会指向不存在的文件，状态不一致（要删就整个目录一起删，见 7.3）
直接删 D:\APP\Node\node_global 会连 pnpm 本体一起清掉
corepack disable pnpm Windows 上报 EPERM，白报错
pnpm add -g pnpm pnpm 12 拦截，报 ERR_PNPM_GLOBAL_PNPM_INSTALL
无验证地跑 pnpm store prune 见上

7.3 彻底清理：删项目 + 回收 store 空间

场景：测试项目、长期不用的项目要清掉，想把磁盘空间真正要回来。 这一节是本机实测踩出来的，三个坑都很容易踩，第三个最阴。

坑 1：pnpm cache prune 清的不是包内容

pnpm 有两套"缓存"，名字长得像，作用完全不同：

命令 清的是什么 在哪个目录 能回收包体积吗
pnpm cache prune registry 元数据缓存（包名→版本→下载地址的索引） pnpm_cache ❌ 不能
pnpm store prune store 里没人引用的包内容 pnpm_store ✅ 能

用错命令的后果：你以为清了 262 MB，实际只清了"黄页电话簿"，包本身一个字节都没动。

坑 2：删项目本身几乎回收不了空间

因为 node_modules 里是硬链接，删掉项目文件夹只是去掉几条引用，数据本体还在 pnpm_store 里躺着。以本机实测的三个项目为例：

删除对象 实际回收 为什么
C:\...\test-pnpm ✅ ~274.7 MB 它是跨盘退化出的真实副本，删了就真回收
D:\11 ❌ 仅 ~3.2 MB + 目录元数据 其余 271.5 MB 是硬链接，数据仍在 store
D:\22 ❌ 仅 ~3.2 MB + 目录元数据 同上

这是《Node 安装与配置》7.3 那条结论的反面印证：共享意味着删除也要一起删才回收。只删项目、不动 store，D 盘那 262 MB 一分都不会回来。

坑 3：项目"删进回收站"＝没删，prune 会拒绝回收 ⚠️ 最阴的一个

这是本机实测撞出来的，很多人根本意识不到。

如果你是从资源管理器删除项目文件夹（或右键 → 删除），文件只是进了回收站——在磁盘上还好端端待着，硬链接依然有效。pnpm 一看："这些包在磁盘上还有别的链接指着呢"，判定仍被引用，拒绝回收。

本机实测两轮对照（同样的命令，只差"项目是否真删"）：

轮次 前置条件 pnpm store prune 输出 实际回收
第 1 轮 项目删进了回收站 Removed 3874 files (2931046 bytes) 仅 2.9 MB ❌
第 2 轮 清空回收站后 Removed 4514 files (268321527 bytes) 255.9 MB / 121 个包 ✅

第 1 轮为什么只回收 2.9 MB？ 对比 store 的构成就清楚了：

store 构成 文件数 字节 prune 结果
独占文件（链接数=1，磁盘上无其他主人） 3877 6.5 MB ✅ 被删（实测删掉 3874 个）
共享文件（链接数>1，回收站里还有主人） 4514 255.9 MB ❌ 动不了（实测保留 4514 个）

根因：回收站里的副本让硬链接数保持 >1，pnpm 判定包"仍被引用"。pnpm 的判断完全正确——回收站里的文件确实还在占磁盘，此时删了 store 的副本反而会让回收站里的东西变成孤儿。

怎么破：

1
2
3
4
5
REM 方式一：删项目时用 Shift + Delete（永久删除，不进回收站）

REM 方式二：删完顺手清空回收站
rd /s /q C:\$Recycle.Bin
rd /s /q D:\$Recycle.Bin

⚠️ 清空回收站前先确认里面没有还要的东西（本机实测回收站里除了测试项目，还有 .dsh 的配置与 skills、旧项目残留等）。只想清项目的话，可以在回收站里单独选中再删。

✅ 正确顺序

删项目时记得"真删"（Shift+Delete，或删完清空回收站），否则第 ② 步只能回收几个 MB——见坑 3。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
REM ① 先删项目
rmdir /s /q "C:\Users\YWH18\Desktop\test-pnpm"
rmdir /s /q "D:\11"
rmdir /s /q "D:\22"

REM ② 关键的一步：清 store 里已无项目引用的包 ← 这才是回收 262 MB 的那步
pnpm --version          REM 先记下版本号
pnpm store prune        REM 执行
pnpm --version          REM 立刻验证！

REM ③ registry 元数据缓存（可选，与包内容无关，清了下次要重新查）
pnpm cache prune

预期回收（按本机三个测试项目实测）：

盘 回收
C 盘 ~274.7 MB（test-pnpm 是跨盘退化出的真实副本，清空回收站后即回收）
D 盘 ~268 MB（store 里的 255.9 MB / 121 个包 + 项目残留）

本机完整实测结果（含"回收站"这个变量）：

阶段 操作 D 盘可用空间
起始 三个项目存在，store 262.4 MB 208.7 GB
第 1 轮 删项目（进回收站）→ pnpm store prune 几乎无变化（只回收 2.9 MB）
第 2 轮 清空回收站 → pnpm store prune 209.0 GB（回收约 310 MB）

最终状态：pnpm_store\v11\files\ 已清空（0 个文件），store 只剩 index.db（约 1.7 MB）；pnpm store status 仍报 Packages in the store are untouched（健康，只是空了）。

⚠️ 第 ② 步执行前后务必验证 pnpm --version。本机的 pnpm 本体装在 node_global（npm 装的）、不在 store 里，理论上不会被误删，但这条命令历史上出过事，验证一下零成本。

关于"想整个清空"

既然项目都删光了，store 就成了纯缓存（没有任何项目引用它）。此时直接删整个 D:\APP\Node\pnpm_store 目录也可以，pnpm 下次装包会自动重建。

但两个前提：

  1. 要删就整个目录一起删（含 index.db）。只删 files/ 留下 index.db，索引会指向不存在的文件，状态就不一致了；
  2. 仍推荐走 pnpm store prune，让 pnpm 自己决定删什么、自己维护索引一致性。

📌 顺带纠正一个常见误解：删 pnpm_store 并不会让已有项目挂掉。硬链接之间是"平等的兄弟"关系，只要还有一条链接在，数据就不会丢（可自行验证：echo x > a.txt → mklink /H b.txt a.txt → 删 a.txt → b.txt 依然完好）。不手删 store 的真正理由只有两条：白删（下次要重下）+ 容易留下不一致的索引。

7.4 维护节奏建议

频率 做什么 命令
装包前随手 确认 pnpm 存活 pnpm --version
每月 更新 pnpm 本体 npm update -g pnpm
每月 清 registry 元数据缓存 pnpm cache prune
每月 跑一次完整体检 见文末体检命令
每季度 npm 官方自检 npm doctor
磁盘紧张时 清 npm 缓存 npm cache clean --force
装 Node 新版后 确认 PATH 无新增重复项 reg query "HKLM\...\Environment" /v Path

7.5 C 盘现在还剩什么（逐项定性）

路径 内容 能否删
C:\Users\YWH18\.npmrc prefix / cache / registry 三行 ❌ 必须保留
C:\Users\YWH18\AppData\Local\pnpm\config\config.yaml 五个 D 盘路径（169 B） ⚠️ 建议保留（删了会重建，无收益）
C:\Users\YWH18\AppData\Local\pnpm\config\auth.ini 腾讯云 registry（48 B） ⚠️ 建议保留（同上，删了镜像源会退回官方）
C:\Users\YWH18\AppData\Local\pnpm-store-operation-locks\ 锁文件 ✅ 可删，自动重建
C:\Users\YWH18\AppData\Local\npm-cache\ 只剩 _logs 残留 ✅ 可删（旧默认缓存目录残留）

已确认不存在（干净）：C 盘的 pnpm.exe / pnpm.cjs、AppData\Roaming\npm、Program Files\nodejs。

判断口诀：C 盘只要没有任何 pnpm.exe，就说明 pnpm 本体没落在 C 盘。 AppData\Local\pnpm\config\ 是配置位不是安装位。

与本文档无关的 C 盘目录（别误伤）：AppData\Local\claude-cli-nodejs\（Claude Code 自己的缓存）、AppData\Local\node-addon-native-custom-loader\（其他工具的 native addon 缓存）。

八、注意事项（踩过的坑）

  1. PATH 里加的是目录不是文件：加 D:\APP\Node，不是 D:\APP\Node\node.exe。
  2. 改完环境变量必须新开命令行：旧窗口不会刷新。
  3. npm config set 不建文件夹：配置路径的目录要先手动建好。
  4. pnpm 的路径项不读 .npmrc：store-dir / global-bin-dir 等必须用 pnpm config set 单独配。
  5. pnpm root -g 末尾带 v11 是正常的：那是按 Node 版本隔离的子目录。
  6. where pnpm 命中 node_global 而非 pnpm_bin 是正常的：因为 pnpm 由 npm 安装。
  7. 不要用 pnpm add -g pnpm 自举：会被 pnpm 12 拦截，改用 npm update -g pnpm 或 pnpm self-update。
  8. 不要执行 corepack disable pnpm：Windows 上会报 EPERM ... unlink（corepack 误把真实安装目录当 shim 删）。忽略报错即可。
  9. PowerShell 执行策略：新开的 PowerShell 跑 npm/pnpm 若报 .ps1 被禁，先执行 Set-ExecutionPolicy -Scope Process Bypass（仅当前窗口有效）。
  10. Windows 路径不区分大小写：D:\APP\node 与 D:\APP\Node 视为同一路径，统一写大写只是为了整洁。
  11. 重装后旧全局包会失效：如果之前在别的路径装过全局包，路径变了会导致 .cmd 快捷方式失效，重新 npm i -g <包> 一次即可。
  12. 项目必须建在 D 盘：硬链接不能跨盘符，项目建在 C 盘 pnpm 就完全不省空间（详见《Node 安装与配置》7.4 / 7.6）。
  13. 别用资源管理器判断省没省空间：它显示的是逻辑大小，硬链接会被重复计算（详见《Node 安装与配置》7.5）。
  14. 删项目要"真删"：走资源管理器删除只会进回收站，硬链接仍有效，pnpm store prune 会拒绝回收（本机实测只回收 2.9 MB）。用 Shift+Delete，或删完清空回收站（详见 7.3 坑 3）。