企业官网建设流程全解析

1. 这个报错到底在说什么

第一次看到[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: @parcel/watcher@2.5.6, canvas@2.11.2这行红字，很多人第一反应是“我是不是装崩了”，然后开始疯狂重装、删node_modules、删 lock 文件，折腾半天发现报错还在。其实这个提示本身不是安装失败，而是 pnpm 在告诉你：有两个依赖包带了postinstall之类的构建脚本，出于安全策略我没有自动执行它们。

先把结论摆出来：你的依赖已经装上了，只是这两个包的构建脚本被 pnpm 主动跳过了。pnpm 从 v10 开始默认禁止依赖包在安装时自动运行构建脚本，原因是供应链安全——防止某个包在postinstall里偷偷干坏事。这个策略本身是好事，但代价就是像@parcel/watcher、canvas这种需要编译原生模块（native addon）的包，脚本不跑就缺东西，运行时才报错。

所以这条报错要分两层看。第一层是“提示”，pnpm 告诉你哪些包的脚本被忽略了；第二层是“后果”，如果这些包确实需要构建产物，那你在实际使用时会遇到Cannot find module、bindings加载失败、canvas引入即崩之类的问题。搞清这两层，解决思路就清晰了：要么让 pnpm 放行这些包的构建脚本，要么确认你根本用不到它们的原生能力。

@parcel/watcher是 Parcel 打包器用的文件监听库，很多构建工具（Vite 某些插件、Parcel 本身、部分 monorepo 工具链）会间接依赖它，它需要编译原生模块来提升文件监听性能。canvas则是 Node.js 环境下的 Canvas 绘图库，底层依赖 Cairo、Pango 等系统库，安装时要编译 C++ 扩展。这两个都是典型的“必须跑构建脚本”的包，被忽略后大概率会出问题。

提示：不要看到红字就慌，先判断这个包在你的项目里是不是真的被用到。有些是传递依赖，实际运行路径根本走不到，那忽略就忽略了，不影响。

2. 为什么 pnpm 要默认忽略构建脚本

要理解这个报错，得先理解 pnpm 的设计哲学。npm 和 yarn 在安装依赖时，默认会执行每个包的preinstall、install、postinstall脚本。这个机制方便了原生模块编译，但也打开了一个巨大的攻击面：任何一个你间接依赖的包，都能在安装时执行任意代码，读取你的环境变量、上传文件、植入后门。历史上出过不少这样的供应链投毒事件。

pnpm 从 v10 起把默认策略改成了“白名单制”：只有你明确允许的包，才会执行构建脚本。这个开关就是package.json里的pnpm.onlyBuiltDependencies字段，或者.npmrc里的相关配置。被拒绝的包会被记录到pnpm.ignoredBuiltDependencies或者直接在安装日志里以ERR_PNPM_IGNORED_BUILDS的形式提示你。

这个设计带来的直接好处是：你的安装过程更可控，不会莫名其妙跑一堆脚本。代价就是原生模块类依赖需要你手动放行。pnpm 官方文档里也说了，这个报错是“warning 级别”的提醒，不是致命错误，它希望你主动做决策，而不是无脑放行所有脚本。

从工程角度看，这个策略其实逼着团队去审视依赖树：到底哪些包需要构建？为什么需要？能不能换成纯 JS 实现？这种“被迫的清醒”长期看是好事。但短期内，尤其是从 npm/yarn 迁移过来的项目，就会遇到这个报错，需要一次性把该放行的包配好。

我自己的经验是，一个中等规模的前端项目，需要放行构建脚本的包通常不超过五个，@parcel/watcher、canvas、esbuild、sharp、better-sqlite3这几个是高频出现的。配一次，之后基本不用再管。

3. 三种解决办法，按场景选

解决这个报错有三条路，没有绝对优劣，取决于你的项目场景和团队规范。我按推荐程度从高到低说。

3.1 方案一：在 package.json 里精确放行

这是最推荐的做法，因为它把“允许哪些包跑脚本”这个决策固化到了代码仓库里，团队成员和 CI 环境行为一致。具体操作是在package.json根级加一个pnpm字段：

{ "pnpm": { "onlyBuiltDependencies": [ "@parcel/watcher", "canvas" ] } }

加完之后重新执行pnpm install，pnpm 就会为这两个包执行构建脚本。注意这里写的是包名，不带版本号，pnpm 会匹配该包的所有版本。如果你只想放行特定版本，可以写canvas@2.11.2这种形式，但一般没必要，包名粒度就够了。

这个方案的优点是精确、可审计、可提交到 git。缺点是每次遇到新的原生依赖都要手动加。不过这正是它的价值所在——你被迫知道自己在放行什么。

3.2 方案二：用 pnpm approve-builds 交互式放行

pnpm 提供了一个交互命令，适合临时处理或者不确定该放行哪些包的时候用：

pnpm approve-builds

执行后它会列出所有被忽略的构建脚本，你用空格键勾选要放行的包，回车确认。pnpm 会自动把选中的包写进package.json的onlyBuiltDependencies里。这个命令本质上是方案一的快捷方式，适合懒人或者快速排查。

我实测下来，这个命令在 pnpm 10.x 上表现稳定，但要注意它修改的是当前项目的package.json，在 monorepo 里要确认改的是根目录还是子包。另外如果 CI 环境是只读的，这个命令会失败，还是得用方案一手动配。

3.3 方案三：全局关闭脚本忽略（不推荐）

有些人图省事，直接在.npmrc里加：

ignore-scripts=false

或者用pnpm config set ignore-scripts false。这确实能让所有构建脚本都跑起来，报错也消失了。但我不推荐这么做，原因很简单：你把 pnpm 辛苦建立的安全防线又拆了。任何一个依赖都能在安装时执行任意代码，供应链风险直接拉满。

如果非要用这个方案，至少限定在本地开发环境，CI 和产线环境保持默认的忽略策略。但更好的做法还是老老实实用方案一，把该放行的包列清楚。

4. 放行之后 canvas 还是装不上怎么办

很多人按上面的方法放行了canvas，结果pnpm install还是报错，错误信息从ERR_PNPM_IGNORED_BUILDS变成了node-gyp编译失败。这是因为canvas不是纯 JS 包，它依赖系统级的 C++ 库：Cairo、Pango、libjpeg、libpng 等等。放行构建脚本只是让编译流程启动，能不能编译成功还得看系统环境。

在 macOS 上，通常需要先装这些依赖：

brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman

在 Ubuntu/Debian 上：

sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

在 CentOS/RHEL 上则是yum install对应的-devel包。Windows 上最麻烦，官方推荐用windows-build-tools或者手动装 Visual Studio Build Tools 加 GTK 相关库，很多人干脆放弃在 Windows 上编译canvas，改用预编译版本或者换@napi-rs/canvas。

这里有个经验：canvas2.x 版本对 Node 版本和系统库版本都比较敏感，Node 18 以上建议用canvas@2.11.2或更高。如果编译一直失败，可以考虑用canvas的预编译二进制，通过设置环境变量CANVAS_BINARY_HOST_MIRROR指向可用的镜像源，或者直接换用@napi-rs/canvas，它是 Rust 实现的，预编译包覆盖全平台，安装体验好很多。

注意：如果你只是用canvas做简单的图片合成，且运行在 Serverless 或容器环境，优先考虑@napi-rs/canvas，能省掉大量系统依赖的麻烦。

5. @parcel/watcher 的坑和替代思路

@parcel/watcher相对canvas温和一些，它编译失败通常是因为缺少 C++ 编译工具链（node-gyp依赖 Python 和 make/gcc）。在大多数开发机上，只要装了 Xcode Command Line Tools（macOS）或build-essential（Linux），放行后就能顺利编译。

但@parcel/watcher有个特点：它提供了预编译的二进制包，按平台分发，比如@parcel/watcher-darwin-arm64、@parcel/watcher-linux-x64-glibc等。pnpm 在安装时会尝试拉取对应平台的预编译包，如果拉到了，其实不需要本地编译。报ERR_PNPM_IGNORED_BUILDS有时候是因为 pnpm 的 optional dependencies 处理逻辑和预编译包的分发机制有交互，导致它认为需要跑构建脚本。

遇到这种情况，可以先确认node_modules/@parcel/watcher目录下有没有对应平台的.node文件。如果有，说明预编译包已经就位，构建脚本忽略也不影响运行，你可以直接忽略这个报错。如果没有，再按前面的方法放行构建。

另外，如果你的项目其实不直接依赖@parcel/watcher，而是某个工具链的传递依赖，可以考虑用 pnpm 的overrides字段把它替换掉，或者确认那个工具链是否支持关闭文件监听的原生实现。比如某些构建工具提供--no-native-watch之类的选项，用纯 JS 的轮询模式替代，虽然性能差一点，但省去了编译麻烦。

6. 从 npm/yarn 迁移到 pnpm 的完整避坑清单

这个报错在迁移场景下特别高频，因为 npm/yarn 默认跑所有脚本，迁移到 pnpm 后突然一堆包被忽略。我把迁移时容易踩的坑整理成一张表，按优先级排列。

迁移时我建议的顺序是：先删掉package-lock.json或yarn.lock，保留package.json；然后pnpm import把旧 lock 转成pnpm-lock.yaml（如果旧 lock 还在）；接着配好onlyBuiltDependencies；最后pnpm install。这样一次性把构建脚本策略定下来，避免反复。

还有一个容易被忽略的点：pnpm 的node_modules结构是符号链接加硬链接的 store 机制，和 npm 的扁平化结构不同。有些包在代码里硬编码了node_modules/xxx的路径假设，迁移后会找不到。这种情况用node-linker=hoisted配置可以让 pnpm 生成类似 npm 的扁平结构，兼容性更好，但会牺牲一部分 pnpm 的空间优势。是否开启取决于你的依赖树里有没有这种“路径敏感”的包。

7. 内网和离线环境的特殊处理

热词里出现了“pnpm 项目迁移到内网”“pnpm 离线”，这确实是企业环境的高频需求。内网环境没有外网访问，canvas这种需要下载源码编译的包会很麻烦，因为node-gyp编译时可能还要下载 Node headers。

内网部署的核心思路是“预热 + 离线安装”。具体步骤：

1. 在有网环境用pnpm fetch把所有依赖下载到 store，包括构建脚本需要的源码包。
2. 把整个 store 目录和pnpm-lock.yaml一起拷贝到内网。
3. 内网机器上配置store-dir指向拷贝过来的 store，执行pnpm install --offline。

但canvas的编译还需要系统库和 Node headers，这些不在 pnpm store 里。所以内网环境更稳妥的做法是：在有网环境把canvas编译好，把生成的.node文件连同node_modules/canvas整个目录打包，内网直接解压使用。或者干脆用@napi-rs/canvas，它的预编译二进制是 npm 包的一部分，pnpm fetch能直接拉到，内网安装无需编译。

对于@parcel/watcher，同样优先依赖预编译包。pnpm 的supportedArchitectures配置可以指定要拉取哪些平台的预编译包，内网机器架构固定的话，提前配好能避免拉错包。

提示：内网环境务必把onlyBuiltDependencies配好并提交到仓库，否则每个开发者本地都要手动 approve 一次，效率极低且容易漏。

8. 几个我踩过的真实坑

说几个文档里不会写、但实际会遇到的坑。

第一个坑：onlyBuiltDependencies配了但没生效。原因通常是配错了位置——它必须在根package.json的pnpm字段下，不能放在子包里，也不能放在pnpm-workspace.yaml里（至少 pnpm 10.x 还不支持在 workspace 文件里配这个）。我见过有人在 monorepo 的子包package.json里配，结果根安装时完全不认。

第二个坑：放行了canvas但 CI 上还是失败。原因是 CI 的 Docker 镜像里没有 Cairo 等系统库，本地能编译不代表 CI 能。解决办法是在 Dockerfile 里加系统依赖安装步骤，或者用多阶段构建，在构建阶段装好编译环境，运行阶段只拷贝产物。

第三个坑：pnpm approve-builds在 CI 里卡住。这个命令是交互式的，CI 环境没有 TTY，执行会挂起或报错。CI 里必须用package.json静态配置，不能依赖交互命令。

第四个坑：删了node_modules重装后报错消失，但过几天又出现。这通常是因为某个依赖升级后引入了新的原生模块，而onlyBuiltDependencies没更新。建议把 pnpm 版本锁定在package.json的packageManager字段里，避免不同机器用不同 pnpm 版本导致策略差异。

第五个坑：ERR_PNPM_IGNORED_BUILDS和ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION同时出现。后者通常是pnpm-workspace.yaml里packages字段缺失或格式错误，先解决 workspace 配置，再看构建脚本的问题，否则会互相干扰排查。

9. 怎么判断一个包到底需不需要放行

最后分享一个判断方法，避免无脑放行所有包。拿到一个被忽略的包，先问三个问题：

第一，它是不是原生模块？看包目录下有没有binding.gyp、prebuilds、*.node文件，或者package.json里有没有gypfile: true、install/postinstall脚本。有这些特征的基本都需要构建。

第二，你的运行路径会不会走到它？用pnpm why <包名>看它是谁的依赖，再判断那条依赖链在你的项目里是否被实际使用。比如你根本不用 Parcel，那@parcel/watcher可能只是某个工具的 optional 依赖，忽略无妨。

第三，有没有纯 JS 或预编译的替代？canvas可以换@napi-rs/canvas，@parcel/watcher可以换chokidar（纯 JS，性能略低但零编译），sharp有预编译包。能换就换，从根上消除构建脚本需求。

这三个问题问完，大部分包该不该放行就清楚了。我的原则是：能不放行就不放行，能换预编译就换预编译，实在不行才精确放行。这样既解决了报错，又不牺牲 pnpm 的安全策略。

我个人在实际操作中的体会是，这个报错看着吓人，其实是个“提醒你审视依赖”的契机。把它当成一次依赖树体检，顺手把不必要的原生依赖清理掉，项目反而更健康。