一、安装

官网

  1. 安装 NVM (Node Version Manager)
1
2
3
4
5
# 下载并运行 nvm 安装脚本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash

# 使 NVM 环境变量在当前的 Shell 会话中立即生效（免重启终端）
. "$HOME/.nvm/nvm.sh"
  1. 安装并启用 Node.js
1
2
3
4
5
# 推荐安装最新的 Node.js 24 (LTS 长期支持版)
nvm install 24

# 验证当前的 Node.js 版本（应输出 v24.18.0 或更高）
node -v
  1. 使用 Corepack 启用并固化 pnpm
1
2
3
4
5
# 启用 Node.js 内置的 Corepack 服务来自动引导 pnpm
corepack enable pnpm

# 验证 pnpm 是否成功激活和挂载
pnpm -v

二、常见故障

hexo 在新设备安装依赖、预览遇到的故障.

2.1 pnpm 无法安装包

1
WARN The "pnpm" field in package.json is no longer read by pnpm

原因：pnpm v11 正式废弃了在 package.json 里的 “pnpm” 字段（如 onlyBuiltDependencies），导致之前的配置完全被忽略，进而导致依赖包本该进行的 postinstall 等构建脚本被静默跳过。

2.2 hexo 报错

  • Error: Cannot find module 'hexo-util'
  • 运行其后提示 WARN No layout: index.html

原因：

  • pnpm v11 做出了重大改变：.npmrc 文件现在仅用于读取镜像源、Registry 认证相关的配置。以前团队习惯在 .npmrc 里写 shamefully-hoist=true，而在 v11 下该配置被直接无视。
  • 由于没有了依赖提升（Hoist），pnpm 回归了最严格的树状软骨架，导致像 butterfly 这样需要动态加载 hexo-util（作为幽灵依赖）的主题无法在平级路径找到对应包，进而加载失败，引发 Hexo 渲染缺失，提示 No layout。

2.3 解决方案

  1. 清理废弃配置：
    打开 package.json，把里面残留的 "pnpm": { "onlyBuiltDependencies": [...] } 一整段代码干净删除并保存，消除废弃警告。
  2. 开启 pnpm 项目级依赖提升（Shamefully Hoist）：
    在根目录运行该命令，pnpm 会自动将配置写入合规的本地配置文件（新版中已迁移至 pnpm-workspace.yaml 中）：
1
pnpm config set --location=project shamefullyHoist true
  1. 重建依赖网络：
    删除受损的 node_modules 并重新安装，此时所有子级和幽灵依赖会被正确扁平化平铺到根目录：
1
rm -rf node_modules && pnpm install
  1. 编译与预览：
1
hexo clean && hexo server