无法找到 @rollup/rollup-win32-x64-msvc

[!info] related notes

• 相关概念: Rollup 模块打包工具, rollup与tsup对比, Build Tools MOC

现象

构建或开发时报错：

Error: Cannot find module @rollup/rollup-win32-x64-msvc

或类似的平台特定 Rollup 二进制缺失错误。

原因

Rollup 从 v4 开始使用平台特定的 optional dependencies 来分发原生二进制文件（替代原来的 @rollup/wasm-node 回退方案）。常见的触发原因：

1. postinstall 脚本失败：安装时平台包的 postinstall 脚本执行失败，但主包安装成功（不会报错）
2. npm/pnpm 缓存损坏：缓存中存在损坏的包文件
3. registry 问题：私有 registry 或镜像源未同步平台特定包
4. 跨平台安装：在一台机器上 npm install，把 node_modules 拷贝到另一平台使用
5. lockfile 过旧：lockfile 中未包含新的 optional dependency 条目

解决步骤

方法一：删除 node_modules 重新安装（最常用）

# Windows PowerShell
Remove-Item -Path "node_modules" -Recurse -Force -ErrorAction SilentlyContinue
pnpm install
# 或
npm install

# Linux/macOS
rm -rf node_modules
pnpm install

方法二：清理缓存后重装

# npm
npm cache clean --force
rm -rf node_modules
npm install

# pnpm
pnpm store prune
rm -rf node_modules
pnpm install

方法三：强制重新构建

# npm
npm rebuild rollup

# pnpm
pnpm rebuild rollup

方法四：确认 lockfile 完整

# 删除 lockfile 重新生成（最后手段，可能引起版本变化）
rm pnpm-lock.yaml  # 或 package-lock.json
pnpm install

预防措施

1. 不要跨平台拷贝 node_modules：始终在目标平台上执行 install
2. 使用一致的包管理器版本：团队约定 pnpm 版本，避免 lockfile 格式差异
3. CI 中缓存 node_modules：使用 CI 平台提供的缓存机制而非手动缓存
4. 定期更新 lockfile：过旧的 lockfile 可能缺少新平台的 optional dependency

信息参考

• Rollup v4 迁移指南
• npm optional dependencies

Related notes

• Rollup 模块打包工具
• rollup与tsup对比
• Build Tools MOC