shadow-cljs构建ClojureScript项目时readable-stream依赖缺失报错排查

• 本次问题是shadow-cljs 2.11.x旧版本的已知兼容问题，核心是模块解析逻辑与npm的依赖提升规则不匹配。
• 按照Node.js标准查找规则，stream-browserify@2.0.2 应该从自身目录下的嵌套node_modules中加载其声明的readable-stream@^2.0.2 依赖。但受npm依赖提升机制影响，项目顶层node_modules中提前安装了由webtorrent间接引入的readable-stream@3.6.0。
• 旧版shadow-cljs的解析器没有严格执行“从被依赖包所在路径向上逐层查找”的逻辑，会直接优先匹配项目顶层的依赖包，导致错配readable-stream@3.6.0。而3.x版本重构了内部文件结构，取消了writable.js的直接顶层导出路径，最终触发文件缺失的编译报错。
• 此前清除缓存、重装依赖的操作没有改变顶层依赖的版本错位状态，因此无法消除报错。

• 首选方案是将shadow-cljs升级到2.20及以上稳定版本。该版本官方重写了NPM模块解析逻辑，完全对齐Node.js的标准依赖查找规则，会正确匹配嵌套路径下的对应版本依赖，从根源解决版本错配问题。升级时修改package.json中devDependencies的shadow-cljs版本号，删除本地node_modules目录和项目根目录下的.shadow-cljs缓存目录，重新安装依赖即可。
• 若暂时不升级shadow-cljs，可任选一种临时修复方式：
  • 在项目顶层dependencies中将readable-stream版本固定为2.3.8，与stream-browserify的依赖要求完全匹配，消除路径错配问题。安装完成后必须删除.shadow-cljs缓存目录，再重启编译监听任务。
  • 在shadow-cljs.edn的前端构建配置中手动添加路径映射，强制所有依赖引用指向正确版本的文件路径，参考配置片段：

    {:builds
     {:frontend
      {:target  :browser
       :modules {:main {:init-fn campfire.core/init}}
       :js-options {:resolve {"readable-stream/writable.js" {:target :npm
                                                             :require "readable-stream@2.3.8/writable.js"}}}}}}
    

• 修复过程中不要执行npm dedupe压平依赖结构，旧版shadow-cljs在压平后的依赖树中更容易出现版本匹配错位，衍生更多同类编译报错。

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