企业官网建设流程全解析

做前端这些年，维护组件库、公共 SDK 的人迟早会遇到一个绕不开的痛点：本地联调。你辛辛苦苦在组件库里改了一个交互细节，切回业务项目想验证效果，发现怎么都不生效，于是开始npm link、重新构建、手工复制dist、清缓存、重启 dev server……一来一回，一上午就没了。如果你也在这个坑里泡过，那 yalc 应该能成为你工具箱里最顺手的一个本地组件库调试工具。

先说清楚 yalc 到底解决什么问题：它本质上是一个“本地包发布器”，把组件库的构建产物（或源码）像发布 npm 包一样发布到一个本地全局仓库，然后在业务项目里以近乎真实 npm 依赖的方式安装进去。相比npm link那种符号链接，yalc 的做法更贴近真实安装，能在最大程度上避免 React 双实例、peerDependencies 解析错乱、lockfile 失效这些老大难问题。这篇文章不打算做官方文档翻译，我会结合自己这几年维护组件库、跨项目联调的实战经验，把 yalc 的原理、用法、工作流和踩坑点一次性讲透，适合正在维护私有组件库的开发者、前端基建负责人，以及在 monorepo 里被包引用问题折磨得死去活来的人。

1. 为什么本地组件库联调需要 yalc

1.1 npm link 的三个致命伤

很多人的第一反应是npm link，它确实是官方提供的能力，用起来也简单：在组件库目录里npm link，到业务项目里再npm link my-lib就完事了。但真正用过的人都知道，这是个大坑。

第一个问题叫“依赖双实例”。组件库一般都会把 React、Vue 这类框架放在 peerDependencies 里，不直接安装。但当你用npm link把组件库链到业务项目时，组件库的文件物理位置还在它自己的目录中，Node 解析模块时沿着符号链接根据真实路径找依赖。这时候组件库的那份 React 可能从全局node_modules里解析，而业务项目里的 React 是自己安装的那份，两个实例并存。对于 React 来说，一份代码里同时出现两个 React 实例，基本上 hooks 全废，经典的 “Invalid hook call” 错误就这么来的。

第二个问题是 postinstall 脚本和构建时机。npm link只做符号链接，它不会触发依赖安装，不会执行 prepare 脚本，也不会帮你处理那些需要在安装阶段完成的构建步骤。组件库从源码到可运行产物之间如果还有 TypeScript 编译、CSS 抽取、d.ts 生成，你必须在 link 之前手动搞定，而且每次改了源码都要重新 build 再手动刷新，非常反人类。

第三个问题藏在包管理器里。npm link不会写入 package.json，不会更新 lockfile，团队其他人拉你代码时根本不知道这个链接存在。更麻烦的是，如果你紧接着跑npm install，某些情况下 npm 会直接把全局链接覆盖掉，链接就断了，错误信息还特别隐晦。pnpm 用户更痛苦，因为 pnpm 对符号链接的隔离策略本身就很严格，npm link在 pnpm 项目里经常直接失效。

1.2 从“文件复制”到“真实验证”：yalc 的设计思路

yalc 没有选择软链接这条路，它的思路非常朴素：把一个本地包“发布”出来，然后像装 npm 包一样“安装”进业务项目。

听起来很像npm pack加file:依赖对不对？但 yalc 比这个更进一步。它会维护一个全局的本地存储目录，把每次发布的包按“包名/版本号”归档；当你通知业务项目安装这个包时，它会把这个包的文件从全局存储复制到业务项目的.yalc目录，并写入file:.yalc/xxx这样的依赖声明。关键点是，业务项目里node_modules中的被引入包，是基于文件副本或受控链接的，也就是说它在 Node 解析路径中所处的位置仍然在业务项目内，peerDependencies 会沿着业务项目的node_modules向上解析。这就在很大程度上规避了双实例问题。

我第一次用 yalc 就是因为 React hooks 报错，npm link折腾了两个小时没解决，换成yalc add之后一次就通了。后来我跟团队里其他人解释 yalc 的优点时，常打一个比方：npm link相当于你在项目里贴了个“指向外面”的便利贴，东西在外面，依赖关系绕来绕去；yalc 相当于把东西先搬进你家的仓库，再自己给自己签收一遍，路径短、关系清楚，当然更可控。

2. yalc 的核心机制与安装部署

2.1 三层结构：全局存储、项目镜像、node_modules

理解 yalc 一定要先理解它的三层结构，不然很多命令和参数会把你绕晕。

第一层是全局存储（store），默认在~/.yalc目录下。你执行yalc publish时，yalc 会把组件库当前的内容打包并复制到这个目录里，路径结构类似~/.yalc/packages/<包名>/<版本号>/。这一层相当于本地私有 npm 源，只不过它只服务你自己。

第二层是业务项目的.yalc目录。当你yalc add <包名>，yalc 会把全局存储里的内容复制到项目根目录的.yalc/<包名>下，同时修改package.json，写入类似"my-lib": "file:.yalc/my-lib"的依赖。这个.yalc目录就是业务项目专属的镜像，它存在的意义是让你可以在不改动全局 store 的情况下，针对不同业务项目做差异化操作。

第三层才是真正被 Node 加载的node_modules。因为 package.json 里写的是file:.yalc/my-lib，你还需要跑一次npm install，让 npm/yarn/pnpm 按 file 协议把它安装进node_modules。有的包管理器对 file 依赖会复制，有的会建链接，但无论如何，它的解析起点已经被拉回到了业务项目内部。

这个三层结构最大的价值是：它把“发布”和“安装”完全拆开了。你可以只发布不安装，也可以对多个项目反复安装同一个本地版本；当你要清理时，也不会像npm link那样留下一堆全局符号链接垃圾。

2.2 快速安装与第一次 publish

安装 yalc 很简单，它是全局 CLI 工具，按你的包管理器来：

npm install -g yalc # 或者 yarn global add yalc # 或者 pnpm 用户 pnpm add -g yalc

装好之后，我建议先在任意组件库目录里跑一次yalc publish看看输出。我以自己维护的一个按钮组件库为例，执行后大致是这个样子：

$ yalc publish yalc p 0.0.1 added to store successfully

这个输出说明当前包已经以package.json里的 name 和 version 进入了全局 store。注意，yalc publish 默认复制的是项目根目录下所有未被忽略的文件，但如果你在package.json里配置了files字段，它也会像 npm pack 一样只打包这些白名单文件。所以组件库发布前，一定要确认files字段包含构建产物目录，比如dist、es、lib，否则 publish 出去的是半成品，业务项目装完照样跑不起来。

第一次 publish 之后，你可以直接到业务项目里执行yalc add my-component-lib，观察 package.json 的变化。你会看到依赖被改写成了file:.yalc/my-component-lib，然后按我前面的提醒执行npm install。装完之后，组件库在业务项目里的表现几乎和真实安装一模一样，这也是 yalc 最打动我的地方。

3. 实操：一次完整的组件库本地联调

3.1 组件库端：publish 与 push

有了基础概念，接下来进入正题：怎么在日常开发里用起来。

组件库端的核心操作是yalc publish和yalc push。publish就是单纯把当前的文件发布到 store，它不会通知任何业务项目；push是 publish 的加强版，它会把新版本同时推送给所有已经add过这个包的业务项目。用一张命令对比来说明：

我自己的开发习惯是：组件库用 Vite 或 tsc 起 watch 模式构建，构建完成后手动执行yalc push。比如组件库的 package.json script 里可以加一条：

{ "scripts": { "dev:yalc": "vite build --watch & yalc push --watch" } }

先说清楚，yalc push --watch并不是监听你的源代码，而是监听 store 里这个包的文件变化。配合vite build --watch，整个链路是这样的：源码改动触发 Vite 重新构建 dist，dist 文件变化导致 store 发生变化，yalc 检测到后自动推送到业务项目。--watch参数不是所有版本都有，如果你的 yalc 版本比较旧，建议先npm update -g yalc升级到最新版，或者退一步用手动yalc push也不亏。

还有一个常用参数叫--replace，它的意思是“无脑覆盖本地存在的对应包”。比如你在业务项目里已经手动改过.yalc目录里的文件，再执行yalc push --replace就会把这些改动全部还原成 store 的最新内容。这在你需要确保业务项目拿到纯净版本时很好用。

3.2 业务项目端：add、link 与 remove

业务项目端最常用的是yalc add、yalc link、yalc update、yalc remove这四兄弟。

yalc add <包名>是标准安装方式，会改 package.json，适合长期调试。yalc link <包名>则相反，它不会动 package.json，只是临时把包放进 node_modules，适合快速验证一下某个改动，改完不想留痕。这两种方式的应用场景差异挺大：如果你需要让团队里所有人都复现同一个联调环境，选 add；如果你只是想在本地临时看一眼某个组件效果，选 link，几分钟就完事。

yalc update是我用得特别多的命令。场景是这样的：你已经在业务项目里yalc add了某个包，然后回到组件库改了一版，又执行了yalc publish。这时候你切回业务项目，执行yalc update my-component-lib，业务项目会从 store 拉取最新的同版本内容覆盖本地镜像。如果组件库改了版本号，yalc update会拉取新版本，但package.json里的 file 依赖不会变，还是指向.yalc/my-component-lib，因为.yalc这个镜像目录本身已经是最新的了。

yalc remove <包名>则负责清理。它会从 package.json 里移除 file 依赖，并删除.yalc目录下对应的副本。你执行完 remove 后记得再跑一次npm install，让 node_modules 里恢复正常依赖。如果业务项目里同时 add 了好几个本地包，想要一键全清，用yalc remove --all最省心。

3.3 开发生效链路：构建+推送的最佳组合

很多新手在刚接触 yalc 时都会问：为什么我yalc push了，业务项目里还是老样子？这个问题九成出在“构建时机”上。

yalc 推送的是文件，不是实时流。组件库里改了源码，如果没跑构建，dist 目录还是旧的，那yalc push推送的自然也是旧东西。所以最理想的状态是：组件库侧先有构建 watcher 把产物持续产出，然后再用yalc push --watch或手动 push 把产物推给业务项目。

我自己在 Vite 组件库项目中配过一次比较顺手的组合，大致流程是：

1. 组件库目录跑vite build --watch，持续生成 dist；
2. 在另一个终端跑yalc push --watch，持续监听 store 变更；
3. 业务项目保持 dev server 运行，改完组件库源码后，等几秒，刷新页面即可看到效果。

这套流程跑起来之后，本地联调的体感非常接近直接在业务项目里写业务代码，几乎没有多余等待。需要注意的是，如果你在业务项目里用的是 Next.js 这类带服务端渲染的框架，修改 node_modules 中的文件可能不会自动触发热更新，有时候需要手动重启 dev server。这不是 yalc 的问题，是框架对 node_modules 的缓存策略决定的，别因为这个误杀 yalc。

4. 进阶场景与配置技巧

4.1 大包场景下优先考虑yalc add --link

默认的yalc add是把 store 里的文件复制到.yalc目录，node_modules 里的实际文件一般通过包管理器的 file 依赖处理。这种模式有一个小缺点：如果组件库非常大，比如包含几十张图片、一堆字体文件，每次update或push都会执行一次文件复制，重复文件多时会明显卡顿。

这时候可以用yalc add --link。加了这个参数后，业务项目 node_modules 中那一层不再是真实复制，而是一个指向.yalc镜像目录的符号链接。当 store 更新后，yalc push只更新.yalc目录里的文件，node_modules 中的符号链接自动生效，省去了重复复制的开销。

有人可能会问：那这个符号链接不是又回到 npm link 的老路上了？其实不是。关键区别在于：这个符号链接的目标是“业务项目自己的.yalc目录”，链的路径短且固定，依赖解析从.yalc向上找 node_modules 时，找的是业务项目内部的 React、Vue。所以 hooks 双实例的问题依然是禁止的，文件同步的效率却大幅提升。对于大包、多包联调，这个模式我很推荐。

4.2 Monorepo 与多包联调

很多团队用 pnpm workspace 管理 monorepo，组件库和业务项目都在同一个仓库里，互相之间直接用 workspace 协议引用。但 workspace 也有不方便的时候，尤其是其中一个包需要“模拟真实发布后”的依赖解析行为时，或者需要把包传给另一个不在仓库里的项目时，yalc 的优势就体现出来了。

在多包场景下，我一般给每个子包单独执行yalc publish，然后在外层业务项目里分别yalc add。不过要注意一个细节：假设组件库 A 依赖组件库 B，而 B 也被业务项目直接安装，Node 可能会为 A 和业务项目解析出两份 B。要避免这个问题，最好在 yalc publish 时用--private参数？不对，--private是跳过包发布到 registry 时限制用的？我在实际使用中一般是在组件库 A 的 devDependencies 里引用 B，保证 B 只从业务项目顶层解析。这一条可能比较绕，但遇到多包互相依赖时，一定要提前想清楚包之间的 peer 关系，别等到运行时才发现有两份同一个组件库副本。

另外，yalc 对 monorepo 里某个子包的构建 watch 支持得不太好，因为 yalc push 是针对单个包名操作的，而 monorepo 往往有几十个子包。我的处理办法是写一个简单的 Node 脚本，遍历 workspace 里所有需要调试的子包，依次执行npm run build和yalc push，把操作批量化。这样脚本化之后，多包联调基本就是一条命令的事。

4.3 与 CI 和版本管理的边界处理

yalc 是本地调试工具，不是发布工具，所以它和 CI 的边界一定要分清楚。我的建议是：所有yalc add产生的.yalc目录必须放进.gitignore，防止本地调试痕迹被提交到远端。像这样：

.yalc

但这里有个非常容易踩雷的点：yalc add会修改 package.json，把依赖从正常版本号变成file:.yalc/my-lib。如果你一时手快，把这个 package.json 提交了，同事 CI 拉下来后npm install找不到.yalc目录，构建直接红掉。所以我在团队里立了一条规矩：提交代码前跑一次yalc remove --all，确认 package.json 里的依赖全部恢复正常版本，再允许合入主干。

如果实在担心自己会忘，可以在项目里加一个 pre-commit 的 lint 脚本，检测 package.json 里是否包含.yalc字符串，有就拦下来：

if grep -q "file:.yalc" package.json; then echo "package.json contains file:.yalc, please run yalc remove --all first" exit 1 fi

这条脚本曾经救过我好几次，强烈建议配上。

5. 常见问题与排查实录

5.1 问题速查表

把我在实际使用中遇到的高频问题整理成一张表，方便你遇到报错时快速定位：

5.2 我自己压过的几个坑

第一个坑是 React 组件库的 “Invalid hook call”。这个错误几乎人人都会遇到一次，而且报错信息特别误导人，会提示你去查官网的“规则”。我当时的实际处境就是 npm link 之后出现这个问题，排查了半天，最后把锅锁定在 React 双实例上。换 yalc 之后，问题一次性解决。原因在于 yalc 把组件库放进业务项目的.yalc目录，所以组件库中require('react')时会沿着.yalc向上找到项目顶层 node_modules 里的 React，跟业务源码用的 React 完全同源。

第二个坑是组件库的package.json里没有配置files白名单。我一开始用 yalc publish 时根本没注意这个字段，导致发布到 store 的文件里包含的是 src 目录源码，而业务项目 import 的入口指向的是 dist，装上之后 import 直接 undefined。这个问题不容易发现，因为它不报错，只是什么功能都没有。

第三个坑和版本号有关。yalc 本身不强制你每次改代码都升版本号，它允许你在同一个版本号上反复 publish 覆盖。但如果你某一次执行了yalc update，且 store 里有新旧两个版本，它默认拉取旧版本还是新版本取决于你的 yalc 版本和命令参数。我的经验是：如果发现 update 之后业务项目拿到的东西和组件库不一致，先执行yalc remove再yalc add --force，强行从 store 拉最新的副本，比纠结版本号更高效。

第四个坑是不要在生产环境依赖里碰 yalc 相关文件。之前有个同事把file:.yalc/xxx的依赖直接待在了 package.json 里提交，CI 第一个任务就开始抹眼泪。后来我们加了前面说的 grep 检查，这种问题就基本绝迹了。如果你是一个团队的基建负责人，我真心建议把这条检查纳入到基础 CI 流程里，成本很低，收益很大。

第五个坑是关于 watch 模式的。我最初在 macOS 上跑yalc push --watch，发现修改文件后偶尔不触发推送，事后排查发现是因为 IDE 的自动保存产生的是原子替换（先写临时文件再 rename），而 yalc 的监听器对 rename 事件支持不太好。解决办法有两个：一是改用编辑器配置，关闭“atomic save”，二是放弃 watch，直接手动按一下 push。我后来选了第二个方案，因为大多数时候组件库构建本身就有延迟，手动 push 的时机更好控制。

结尾：这套工具的边界与我的习惯

说到底，yalc 不是万能的，它解决的是“本地联调模拟真实安装”这一类问题，而不是源码同步问题。如果你的组件库代码量不大，改动不频繁，那npm link凑合也能用；但如果你像我一样维护了多个业务项目共用的组件库、SDK，天天在 link 和 rebuild 之间来回折腾，那 yalc 带来的收益是立竿见影的。

我现在的工作流已经固定成了：组件库侧开构建 watcher，业务项目侧用yalc add或--link模式引入，每次改完组件库源码后习惯性按一下yalc push，然后继续在业务项目里验证效果。这个习惯帮我省下了大量时间，也让我在排查那些“本地好好的，上线就报错”的案件时，少了一个干扰变量。

最后再分享一个小技巧：如果你有多个组件库需要同时联调，不要一个个手动切目录去执行 yalc 命令，写一个简单的 shell 脚本批量处理，把for dir in packages/*; do (cd $dir && npm run build && yalc push); done这样的循环跑起来，效率会提升很多。本地调试工具本来就是为了让开发过程顺滑，别让它变成新的负担。