2023年：缓存node_modules后如何让npm仅执行工作区链接？

一、仅执行工作区链接的解决方案 #

要跳过npm ci的依赖检查步骤，只完成工作区包的软链接创建，可以通过以下两种方式实现：

1. 批量执行npm link脚本 #

利用npm的工作区查询命令获取所有包路径，逐个执行链接操作：

# 获取所有工作区包的路径
WORKSPACES=$(npm query .workspace | jq -r '.[].location')

# 为每个工作区包创建本地链接
for workspace in $WORKSPACES; do
  cd "$workspace" && npm link && cd -
done

# 在根目录或目标应用目录，链接所有工作区包到当前项目的node_modules
npm link $(npm query .workspace | jq -r '.[].name')

这个流程会直接在node_modules中创建指向工作区源码的软链接，完全跳过外部依赖的校验与安装。

2. 精简版npm install命令 #

如果你已经缓存了完整的node_modules（外部依赖已安装），可以用以下命令仅触发工作区链接，跳过其他冗余操作：

npm install --no-ci --no-audit --no-fund --ignore-scripts --no-save --workspaces

参数说明：

• --no-ci：跳过严格的package-lock校验
• --ignore-scripts：不执行任何install/postinstall脚本
• --no-save：不修改package.json或lock文件
• --workspaces：仅处理工作区相关的链接逻辑

二、缓存node_modules的不稳定因素 #

即使你通过package-lock的校验和来管理缓存失效，仍存在以下风险：

• 跨平台软链接兼容性：Windows环境下创建软链接需要管理员权限，部分CI容器的文件系统（如某些轻量容器）可能不支持符号链接，导致链接失效。
• 绝对路径依赖问题：如果工作区的软链接使用绝对路径，CI环境的临时目录每次构建可能不同，会导致链接指向不存在的路径。建议确保npm生成相对路径的软链接（npm v7+默认支持相对路径链接）。
• Native模块环境不兼容：依赖Node版本、系统架构的原生模块（如sharp、node-sass），在缓存后如果CI环境的Node版本、操作系统变更，缓存的编译产物会直接失效，导致运行时错误。
• 工作区代码变更未触发缓存更新：如果工作区包的源码修改但版本号未更新，你的缓存失效逻辑（基于不含工作区版本的lock校验和）不会触发缓存更新，可能导致应用使用旧的缓存链接，引发代码不一致问题。
• 循环依赖导致的链接异常：工作区之间存在循环依赖时，npm link可能会创建异常的链接关系，导致模块加载路径混乱，引发运行时错误。

三、相关实践情况 #

社区中不少使用npm工作区的monorepo项目都尝试过这种缓存方案，尤其是在CI构建耗时优化场景下。比如一些前端框架的子项目、企业内部的模块联邦项目，会通过自定义脚本缓存工作区的node_modules，再结合npm link重建链接来节省构建时间。不过多数大型项目会配合pnpm、Rush等更适合monorepo的包管理器，它们内置了更可靠的缓存与工作区链接机制，能减少手动处理的风险。

内容的提问来源于stack exchange，提问作者Phil