实战干货 | Turborepo：组件设计

我见过太多人用Turborepo做组件设计，一上来就堆代码，结果背负了复杂的依赖和庞大的构建时间。Turborepo不是用来简化你的代码，而是用来优化你的构建流程和管理多包项目的协作逻辑。组件设计的核心不在于写多少文件，而在于如何把这些文件划分为可复用的单元，同时保证构建效率和团队协作的流畅。我见过有人把整个项目都搞成一个包，结果每次改动都要全量重建，速度慢得像蜗牛。也有人把每个组件都单独拆包，结果依赖关系混乱，build缓存全乱套。

你要是想用Turborepo做组件设计，得从一开始就搞清楚组件的边界和依赖层级。每个组件应该是一个独立的包，内部有完整的入口文件和测试配置。别偷懒，别怕麻烦，用好`workspace:`的语义，别把包之间的依赖关系搞成一个大杂烩。我见过有人在`package.json`里随便加依赖，然后build就崩了，因为Turborepo的缓存机制根本无法识别这种混乱。而且，组件之间要保持松耦合，不要搞成单向依赖，这样你才能在不重启项目的情况下对一个组件做修改。

build命令的配置是关键。比如你用`turbo run build`，默认会运行`build`脚本，但如果你的组件需要不同的构建策略，就得在`turbo.json`里手动指定。我记得有个项目因为没有配置`build`的`tasks`参数，导致每个组件的构建都全量执行，build时间直接翻倍。还有人用`--filter`参数来限制构建范围，比如`turbo run build --filter @myorg/ui-components`，这样可以只构建某个组件，而不是整个项目。脚本部分得写踏实，不能靠默认配置混过去。

别忘了配置`workspace:`的文件结构。如果你用的是Monorepo，得让Turborepo知道哪些目录是工作区。我在实战中发现，如果目录结构混乱，比如组件和工具包混在一起，Turborepo的缓存就完全失效了。另外，组件的依赖要尽量使用workspace依赖，避免用npm安装，这是性能提升的关键。如果有组件需要外部依赖，也得合理配置`resolutions`或者`overrides`，否则build可能会因为版本冲突出问题。

还有个隐藏的坑，就是组件的入口文件和测试入口要统一路径。比如`src/index.js`和`test/index.js`，如果不统一，Turborepo的检测机制就无法识别，导致build缓存失效。我记得有个项目因为测试入口路径不对，每次修改测试代码都触发全量build，性能直接崩溃。另外，公共组件的构建逻辑要尽量统一，比如都用`@rollup/plugin-node-resolve`和`@rollup/plugin-commonjs`，否则不同组件的构建结果会不一致，容易引入bugs。

组件的版本管理也得注意。Turborepo支持yarn workspaces和npm workspaces，但实际使用中，我更推荐yarn workspaces，因为它对组件的版本控制更灵活。比如你可以在每个组件的`package.json`里写`"version": "1.0.0"`，然后用`yarn install`自动更新依赖。不过要小心别在组件的`package.json`里写`"private": true`，这样它们就无法被其他项目引用，也不方便共享。我见过有人为了追求模块独立性，把所有组件都设为private，结果项目之间互相依赖时根本无法运行。

在实际项目中，组件设计要和CI/CD链路打通。比如你用GitHub Actions，可以配置不同的build任务对应不同的组件。用`--filter`参数来指定构建哪些组件，这样可以显著减少每次build的时间。另外，你要是用TypeScript，得在`tsconfig.json`里配置`composite`为true，这样TypeScript就能正确识别组件的依赖关系，避免类型错误。同时，构建时要确保`types`字段正确指向组件的类型定义文件，否则IDE的类型提示就会失效。

组件的测试也要分门别类。比如你可以用`@testing-library/react`来跑UI测试，用`jest`来跑单元测试。但别把所有测试都放在主项目的`test`目录下，这样会干扰构建缓存。每个组件的测试目录应该放在自己的包里，比如`@myorg/ui-components`包里的`test`目录。用`turbo run test --filter @myorg/ui-components`来单独跑这个组件的测试，这样既能保证单元测试的准确性，又能提升CI的效率。记得给每个组件的测试配置独立的`jest.config.js`，避免全局配置带来的副作用。

如果你的组件需要发布到npm，那build配置必须准确。比如你用`turbo run build`生成`dist`目录，然后用`turbo run publish`来发布。与此同时，每个组件的`package.json`里要写清楚`main`和`types`字段，否则用户安装后没法正常使用。我见过有人没写`main`，导致npm install后找不到入口文件，项目都跑不起来。还有人为了兼容性，把`umd`和`esm`都打包进去，但这样build时间会增加30%以上，除非你用`rollup`的`treeshaking`来优化。

组件的依赖版本管理要细致。比如你用`resolutions`字段来限定依赖版本，这样就能避免不同组件之间的依赖冲突。但要小心别把`resolutions`写得太死，否则在开发时可能会因为版本不匹配导致问题。我见过有人在`resolutions`里强制安装`react@18.0.0`，结果某个组件的依赖链里用了`react@17.0.0`，导致构建失败。一般来说，建议在`package.json`里用`workspace:`来管理依赖，这样既保证版本一致性，又不会影响开发体验。如果你需要更细粒度的控制，可以结合`overrides`字段来实现。

构建缓存的优化是Turborepo的核心价值之一。每个组件的构建任务都应该有明确的缓存键，这样当依赖没变时，build可以复用之前的输出。我之前在项目中遇到缓存失效的问题，是因为没有正确配置`cacheKey`。比如你在`turbo.json`里写`"cacheKey": "${cwd}#${dir}#${name}"`，这样就能让缓存更准确。另外，如果你用的是`@rollup/plugin-node-resolve`和`@rollup/plugin-commonjs`，记得在`rollup.config.js`里配置`input`和`output`，确保每个组件的入口文件被正确识别。

不要把所有的组件都放在同一个目录里。这样做会让Turborepo的缓存机制失效，因为目录结构太复杂，它无法区分哪个组件需要重建。我见过一些项目把所有组件都放在`src/components`目录下，结果每次修改一个组件都要重装整个依赖，build时间直接拉长到10分钟。正确的做法是按业务模块划分目录，每个目录对应一个组件包。比如`src/ui`对应UI组件，`src/utils`对应工具函数，这样Turborepo就能准确识别每个组件的变化范围，减少不必要的build。

组件的构建配置要尽量共享。比如你可以在`turbo.json`里定义通用的build任务，然后在每个组件的`package.json`里引用。比如`"build": "turbo run build"`，这样每个组件都用同一个build流程。如果你的组件需要不同的构建参数，比如有的用`--optimize`，有的用`--dev`，可以在`turbo.json`里通过`tasks`字段配置不同的参数组合。这样你就可以用`turbo run build --filter @myorg/ui-components`来触发特定组件的构建，同时保持构建逻辑的一致性。

组件的测试覆盖率也要考虑。Turborepo支持在`turbo.json`里配置`coverage`任务，比如`"coverage": "turbo run coverage"`。这样你就可以用`turbo run coverage --filter @myorg/ui-components`来单独获取某个组件的测试覆盖率。不过要注意，如果组件的测试覆盖率太低，可能会影响你对组件质量的判断。我记得有个项目测试覆盖率只有50%，结果上线后一堆bug，最后不得不全量重写。所以测试覆盖率必须作为组件设计的一部分，不能靠后期补救。

别忽略构建时的环境变量。比如你在`turbo.json`里配置`env.NODE_ENV=production`，这样就能确保构建时使用的是生产环境的配置。如果是某个组件需要特殊参数，比如数据库连接字符串，可以在`env`里单独配置。比如`"env": {"DATABASE_URL": "myprodurl.com"}`。这样每个组件在build时就能自动识别环境，避免配置错误导致的build失败。我之前有个项目因为没配置环境变量，导致测试环境的build用的是生产配置，结果测试数据全错。

如果你的组件需要依赖其他组件，别用workspace依赖。有些时候，workspace依赖在build时会把依赖关系搞成环，导致build流程崩溃。所以要确保每个组件只依赖它需要的，不要盲目引用。比如你有个UI组件依赖了另一个工具组件，那就要在`package.json`里写`"@myorg/tool-utils": "workspace:"`。但要注意别让工具组件依赖UI组件，这样就会形成环依赖，build就会卡死。我见过有人用这种错误方式，最后build卡在100%进度，完全无法退出。

在实际项目中，组件的构建配置要尽可能模块化。比如你可以用`@turborepo/manager`来统一管理build流程，然后每个组件的`package.json`里写`"scripts": {"build": "turbo run build"}`。这样你就可以在终端里统一触发所有组件的build。或者你用`@turborepo/manager`的`tasks`字段来定义不同的构建策略，比如有的组件需要打包，有的只需要运行。这样能显著提升构建效率，避免全量build的低效。我记得有个项目把所有组件都设成全量build，结果一天build三次，每次都要15分钟以上，团队怨声载道。

最后，别把组件设计当成一次性任务。组件的边界要随着项目发展不断调整。我见过有的项目初期把所有组件都放在一起，结果后来因为组件逻辑耦合太紧，不得不重新拆包。所以要保持组件的灵活性，不要死守目录结构。用`workspace:`来动态管理依赖，这样即使重构目录结构，Turborepo也能自动适应。另外，组件的构建配置要能支持多平台，比如同时支持Web和Node，这样你才能确保组件在不同环境下的兼容性。别让某个组件只适应一个平台，否则他的复用性就会大打折扣。