企业官网建设流程全解析

【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除

背景

上篇 blog
【Agent】【OpenCode】项目配置（根目录&子包配置）
分析了 OpenCode 项目中所有package.json文件的位置，项目中这么多的package.json是因为 OpenCode 采用的是 Monorepo（单体仓库）的架构，在该架构下，整个项目被拆分成多个功能独立的子包（Packages），共同存放在一个代码仓库中，根目录和子包目录下的package.json扮演着完全不同的角色，其中根目录下的package.json作为全局大管家，是整个 Monorepo 的基础配置，里面定义了工作区（Workspaces），工作区声明了包含哪些子目录，以便包管理器（Bun）能统一处理所有子包依赖的安装，并管理全局开发依赖，而子包目录下的package.json用于定义该独立模块自身的专属信息，比如记录依赖的第三方库，入口与可执行文件配置等，最后分析了不把所有依赖都放在根目录的package.json中的原因，下面继续分析

OpenCode

上篇 blog 提到了包管理器 Bun 会同时解析根目录所有子包的配置，统一把依赖下载到对应的node_modules中，然后举了两个例子：根目录下的node_modules和子包目录下的node_modules，由于不同子包的package.json是独立管理依赖的，就不可避免会出现同一个包同时出现在多个package.json的依赖中，这通常出现在版本控制策略不同的场景中，比如

• 根目录可能使用范围版本，比如"typescript": "^5.0.0"，作为团队统一的底线要求
• 子包可能写死精确版本，比如"typescript": "5.4.2"，或者锁定一个不同的兼容版本

此时包管理器在解析时会分析同一个包，在不同依赖上，对应版本的交集，这种在 Monorepo 中看到的，同一个依赖出现在不同package.json里，在底层机制上会引发一种叫做依赖分身（Doppelgangers）的现象

• 在传统 Npm 扁平化机制下，如果包 A 和包 B 都依赖了lodash，但版本要求不同（比如 A 要^4.0.0，而 B 要^3.0.0），或者因为嵌套层级过深，包管理器无法将它们合并到同一层，就会导致lodash被重复安装多次，这种现象被称为依赖分身，会大量消耗硬盘空间，增加依赖维护成本

在 Monorepo 现代工具（如 PNpm，Bun 等）中，会通过一些方法来解决这种物理上的重复，比如

• 全局存储与硬链接：PNpm 会将所有子项目的依赖打平到一个全局的内存中，无论多少个package.json引用了同一个版本的lodash，这个依赖在物理磁盘上也只会被下载一次，而各个项目通过硬链接共享这一份实体文本，可以极大地节省空间

• 软链接关联本地包：对于 Monorepo 内部的子包互相引用，PNpm 会通过符号链接（软链接）来实现实时调试，而无需发布的 Npm

OK，底层已经通过硬链接解决了物理空间的浪费，那么为什么还要在各个子包的package.json中写上相同的依赖呢？这里涉及到两个点

• 严格的边界隔离（防止幽灵依赖）：如果不显式声明，开发者很容易不小心用到某个没安装的包（也就是幽灵依赖），虽然这个包可能碰巧被其他子包安装了，但一旦那个子包升级后不再需要它，那没显式声明的子包就会瞬间崩溃，而 PNpm 的非扁平化结构强制要求，子包必须在自己的package.json中声明依赖，才能在代码中 require 或 import 来引用它
• 应对复杂的对等依赖（peerDependencies）：当多个子包对同一个依赖有不同版本的要求时，为了保证各自的运行环境正确，包管理器可能会为同一个包创建多份上下文拷贝，比如针对不同的 baz 版本，生成

mailto:bar@1.0.0mailto:+baz@1.0.0
mailto:bar@1.0.0mailto:+baz@1.1.0

两份虚拟目录，这时候，子包内各自精确的声明就是保证各模块互不干扰的底线

对于当前的 OpenCode 项目，为了避免到处维护相同的版本号，有如下处理措施：

• Workspace 协议（workspace）：比如"@opencode-ai/script": "workspace:*"，就是在告诉包管理器，不要从 Npm 上下载这个包，直接链接到当前仓库里的另一个子包，这里就解决了内部模块互相引用的问题
  

• Catalogs（目录功能）：Bun，PNpm 等包管理器支持在根目录定义一个统一的版本目录 Catalog，然后各个子包只需声明"express": "catalog:"，就能自动继承根目录定义的精确版本，这样既保证了不重复，又实现了全局统一升级
  

OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog