拓冰建站拓冰建站
首页 / 资讯中心 / 正文

sample-monorepo 常见问题排雷指南:7 个坑解决依赖提升与构建报错

sample-monorepo 常见问题排雷指南7 个坑解决依赖提升与构建报错【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepoSample monorepo 是一个基于npm workspaces与TypeScript project references搭建的多包仓库示例把前端应用、组件库与服务端放在一个仓库里统一管理。很多新手在第一次 clone 并运行npm install、npm run build时都会遇到依赖提升hoisting导致版本错乱、tsc --build增量构建报错等头疼问题。这篇文章就为你整理 7 个最常见的坑帮你快速排雷少走弯路。一、依赖提升Hoisting是什么为什么它最容易踩坑npm workspaces 默认会把所有包的公共依赖提升hoist到根目录的node_modules而不是每个包各装一份。这本来是节省磁盘、加快安装的设计却常常带来两个问题版本冲突两个子包对同一个依赖要求不同版本提升后可能只保留其中一个导致运行时拿到错误的 API。幽灵依赖Phantom Dependency你的代码能 import 到某个包但它其实并没有写进自己的package.json只是因为提升后被顺带装上了换台机器就立刻报Cannot find module。排雷建议根目录package.json里的workspaces字段声明了packages/*安装时务必在仓库根目录执行npm install不要跑到子包里单独装子包要用到的依赖一定要显式声明在自己的package.json中。二、改完 package.json 不重新安装报 Cannot find module这是出现频率最高的一类构建报错。很多人修改了某个包的依赖后直接运行npm run build结果提示找不到模块其实只是因为lockfile 和 node_modules 还没同步。最快解决办法在根目录重新执行一次npm install必要时先清空node_modules和package-lock.json再装让 npm workspaces 重新解析依赖树。根目录的package-lock.json是整个 monorepo 的依赖清单别只在子包里折腾。三、tsc --build 增量构建报错tsbuildinfo 缓存惹的祸项目根目录的build脚本是tsc --build它依赖 TypeScript 的增量编译缓存.tsbuildinfo 文件。当你改了某个包的接口签名、或者改了 tsconfig旧缓存没失效就会出现明明代码改了却报错的诡异情况。排雷建议项目提供了clean脚本rimraf -g ./packages/*/dist先执行npm run clean再重新构建如果还不行把各包dist下的*.tsbuildinfo一并删掉。记住一条铁律改完 tsconfig 或跨包接口后先 clean 再 build。四、Project References 报错缺少 composite 配置用 TypeScript 项目引用Project References时被引用的项目必须开启composite: true否则会报Referenced project must have setting composite: true。项目的 tsconfig.base.json 已经默认开启了composite并声明了declaration、declarationMap、sourceMap等输出配置。各子包的 tsconfig 通过extends继承这份基础配置例如 packages/components/src/tsconfig.json、packages/app/src/tsconfig.json 只额外配置了outDir和references。如果你自己新建包一定要记得 extends 基础配置或手动加上composite: true否则根目录 tsconfig.json 里的 references 会直接构建失败。五、module: node16 下的导入报错扩展名与类型导入基础配置里module和moduleResolution都是node16同时还开启了verbatimModuleSyntax。这意味着相对导入必须写完整扩展名import { x } from ./main.js不能省略.js源码里写.js编译后指向真实文件。看 packages/components/src/index.ts 就是export * from ./main.js的写法。纯类型导入必须用import type否则开启verbatimModuleSyntax后类型会被当成运行时导入报仅用作类型的错误。排雷建议报Cannot find module或类型导入错误时优先检查这两点八成能解决。六、跨包引用顺序错误dist 还没生成就构建monorepo 里包与包之间是相互依赖的sample/app依赖sample/components见 packages/app/package.jsonsample/server又依赖sample/app见 packages/server/package.json。而子包通过exports指向./dist/index.js也就是说被依赖的包必须先完成编译否则上游会读到不存在的 dist。TypeScript 项目引用在tsc --build时会按依赖顺序自动构建所以推荐统一在根目录用npm run build而不是单独cd进子包构建。改动了公共包后务必先构建它再构建依赖方。七、Node 与 npm 版本不匹配engines 字段的硬性要求最后一个常被忽略的坑项目在根 package.json 的engines里声明了node 22、npm 8。如果你本机 Node 版本过低安装或构建时会直接报版本不满足或者出现各种语法/行为异常。排雷建议先用node -v和npm -v确认版本必要时通过 nvm 切换版本对了很多玄学报错会瞬间消失。总结一套标准的排雷流程遇到问题别慌按这个顺序排查确认 Node ≥ 22、npm ≥ 8在根目录执行npm install确保依赖树与 lockfile 同步执行npm run clean清掉旧的 dist 与增量缓存用根目录的npm run build按依赖顺序统一构建还有报错重点检查node16下的导入扩展名与import type写法。最后提醒一句如果你想在本地复现这套 sample monorepo 环境可以git clone https://gitcode.com/gh_mirrors/sa/sample-monorepo后按上面的流程走一遍。依赖提升与构建报错并不可怕理解 npm workspaces 和 TypeScript 项目引用的协作机制7 个坑都能轻松绕开。【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
分享:

看完干货,该让你的企业上线了

免费需求沟通 · 48 小时内出具建站方案 · 河南本地可上门