Nx缓存是否支持保留符号链接？

问题场景 #

我有一个Nx monorepo项目，其中包含一个node_modules/.bin文件夹，内容如下：

drwxr-xr-x   84 demo  staff   2688 Dec  8 13:29 .
drwxr-xr-x  997 demo  staff  31904 Dec  8 13:29 ..
lrwxr-xr-x    1 demo  staff     20 Dec  8 13:29 JSONStream -> ../JSONStream/bin.js
lrwxr-xr-x    1 demo  staff     18 Dec  8 13:29 acorn -> ../acorn/bin/acorn
lrwxr-xr-x    1 demo  staff     29 Dec  8 13:29 ag -> ../@asyncapi/generator/cli.js

该文件夹已配置为可缓存。

执行构建后，查看.nx/cache/.../outputs/node_modules/.bin中的对应缓存内容时，符号链接消失了：

-rwxr-xr-x    1 demo  staff    251 Aug 25 11:27 JSONStream
-rwxr-xr-x    1 demo  staff     60 Aug 25 11:26 acorn
-rwxr-xr-x    1 demo  staff   7780 Aug 25 11:26 ag

缓存恢复后运行ag时出现错误：

REDACTED/node_modules/.bin/ag [..additional parameters..]

node:internal/modules/cjs/loader:936
  throw err;
  ^

Error: Cannot find module './package.json'
Require stack:
- /REDACTED/node_modules/.bin/ag
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/REDACTED/node_modules/.bin/ag:8:21)
    at Module._compile (node:internal/modules/cjs/loader:1105:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1159:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:77:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/REDACTED/node_modules/.bin/ag'
  ]
}

恢复符号链接后一切正常。我期望Nx缓存机制能够保留符号链接，这是预期行为吗？

结论与说明 #

这不是Nx的预期行为，而是Nx缓存机制在处理符号链接时的已知限制。

Nx默认缓存输出时会将符号链接解析为实际文件内容（复制链接指向的文件，而非保留链接本身），导致缓存恢复后原本的符号链接变成独立文件。而node_modules/.bin中的脚本通常依赖相对路径定位包核心文件，当脚本变成独立文件后，相对路径基准改变，自然找不到对应模块。

临时解决方案 #

• 排除node_modules/.bin缓存：node_modules目录通常无需Nx缓存，可通过npm install重新生成。在nx.json的ignoredPaths或cacheableOperations配置中排除该目录。
• 缓存恢复后重建链接：执行npm rebuild或手动调用ln命令重新生成符号链接。
• 升级Nx版本：较新版本Nx对符号链接处理有优化，尝试升级到最新稳定版，部分版本支持通过配置开启符号链接保留功能。

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