开源项目的示例代码依赖如何管理

本文目录导读：

1. 最推荐：使用独立的包管理文件（独立项目）
2. 较推荐：工作区（Workspace）方案
3. 不推荐：统一放在根 package.json 中
4. 特殊场景：测试/集成测试示例脚本
5. 总结与建议清单

这是一个很好的问题，在开源项目中，示例代码（Example Code） 的依赖管理确实是一个特殊的挑战：它需要既可复现（让用户能直接跑起来），又不能给主库（Core Library）的构建过程带来额外的负担或冲突。

最佳实践的核心原则是：让示例代码拥有独立的依赖生命周期，与主库的依赖完全隔离。

以下是几种主流的、从简到繁的管理策略：

最推荐：使用独立的包管理文件（独立项目）

这是最清晰、最安全的方式，在项目仓库的根目录下，创建一个 examples/ 目录，并在其中为每个独立的示例（或使用示例集合）创建独立的配置。

如何操作：

• 目录结构：

  my-project/
  ├── src/                # 主库源码
  ├── package.json        # 主库依赖（React, Lodash）
  └── examples/
      ├── basic-usage/
      │   ├── package.json   # 示例专用依赖（比如一个特定版本的 Node.js 框架）
      │   ├── index.js
      │   └── README.md
      └── with-react/
          ├── package.json
          ├── index.jsx
          └── ...

• 示例的 package.json： 该文件通过 dependencies 或 devDependencies 引用你的库：

  {
    "name": "example-basic-usage",
    "private": true,
    "dependencies": {
      "my-library": "file:../../",  // 关键：指向主库的本地路径
      "some-unrelated-tool": "^1.0.0"
    }
  }

  • "file:../../"：这是关键所在，它告诉包管理器“这个依赖就放在我上级的上级目录里”，当你运行 npm install 时，它会把你的主库直接链接过来，就像用户从 npm 安装了你的库一样，这既能测试库的真实可用性,又不会发生版本冲突。

优点： 隔离性极好，依赖完全独立，示例可以被当作独立的子项目来开发、测试和贡献。 缺点： 稍微增加了一点仓库复杂度，每个示例都需要运行 npm install。

较推荐：工作区（Workspace）方案

如果你有很多示例，且它们共享一些公共工具（如构建工具、测试框架），或者你希望在一个命令下管理所有示例的依赖,工作区方案是更好的选择。

如何操作：

• 主库的 package.json：

  {
    "name": "my-library",
    "workspaces": ["examples/*"],  // 声明 examples 下的所有子目录都是工作区
    "dependencies": { ... }
  }

• 示例的 package.json： 与第一种方法类似，仍使用 "my-library": "file:../../" 来引用主库。
• 根目录运行： 在项目根目录运行 npm install，它会自动将所有工作区（包括所有示例）的依赖安装到一个顶层的 node_modules 中,并自动创建符号链接。

优点： 管理集中（一个npm install搞定所有），节省磁盘空间，共享公共工具方便，对于多示例的大型项目非常有用。 缺点： 配置稍复杂（需要理解工作区）,极端情况下可能因示例间依赖不同导致版本冲突。

不推荐：统一放在根 package.json 中

这是新手最容易犯的错误——把示例需要的依赖也放到主库的 dependencies 或 devDependencies 里。

为什么不推荐？

• 污染用户环境： 用户安装你的库时，会把示例依赖（比如一个过时的测试框架）也装进去。
• 不必要的负担： 用户用你的库，为什么需要下载一个展示用的 UI 库？
• 版本冲突： 示例依赖的框架（React 18）可能与主库（React 16）冲突,导致用户项目崩溃。

特殊场景：测试/集成测试示例脚本

如果你的示例更像“如何集成”的脚本（比如一个 .sh 脚本或一个简单的 Python 脚本），而不是一个完整的项目,可以采用更轻量的方式。

场景： 一个 C 库的示例是 .c 文件。 做法： 在 examples/Makefile 中直接指定头文件和库路径，让用户自己编译，或者在文档里写清楚 gcc -I../include -L../lib ...。

更性感的做法： 使用 Docker。 将示例封装成一个 Docker 容器，用户只需 docker run，无需关心环境配置，这种方案的隔离性最好，但需要维护 Dockerfile。

总结与建议清单

最终建议：

1. 默认选择方案 1：为每个示例创建一个独立的子目录，并在其 package.json 中使用 "my-library": "file:../../"。

2. 如果你在用 npm、yarn 或 pnpm，并且示例数量较多或共享构建工具，升级到方案 2（工作区）。

3. 无论哪种方式，务必在你的 README.md 或 CONTRIBUTING.md 中写明示例如何运行，

   ## Running Examples
   cd into an example directory:
   cd examples/my-example
   Install dependencies (link to the local main library):
   npm install
   Run the example:
   npm start

这样，你的示例代码对你（开发者）来说是可维护的,对用户来说是友好且可复现的。