NPM包开发：配置示例专属依赖 实现依赖隔离避免多余安装

你遇到的场景本质是单代码仓库下同时承载「对外发布的核心NPM包」和「仅内部展示用的演示项目」，核心目标是把两者的依赖边界彻底切开，不让演示项目的依赖被普通用户安装。下面是实际项目验证过的可落地方案，没有冗余的流程设计：

核心配置逻辑 #

1. 先给根目录的核心发布包划清依赖边界 #

所有属于核心包的依赖严格按照npm规范分类，从根源上控制用户安装时的拉取范围：

• dependencies 字段只放 repo/src/maincode.js 运行时必需的生产依赖，这部分才是用户安装时会自动拉取的内容
• devDependencies 字段只放核心包开发、构建、测试需要的工具类依赖（比如打包器、测试框架、代码检查工具），这部分依赖在你发布NPM包时会被npm自动过滤，不会推送给普通用户
• 必须在根目录package.json里配置files字段，明确指定发布时需要上传到npm仓库的文件路径，比如写 "files": ["dist", "src"]，从打包环节就避免把examples目录的内容打进发布包——这是90%的开发者踩过的坑，哪怕依赖隔离做的再好，把整个示例目录打到发布包里，包体积会凭空增加几百K。

2. 把examples目录做成独立的依赖作用域 #

这是解决问题最干净的方案，比任何“触发式安装”的奇技淫巧都靠谱：

• 绝对不要把演示项目需要的React、Vite等专属依赖扔在根目录的package.json里——根目录的所有依赖都会被纳入npm的安装链路，用户执行npm i 你的包的时候，很容易顺带把这些演示依赖拉下来，平白增加安装体积。
• 直接在repo/examples/react目录下新建一个完全独立的package.json文件，把演示项目需要的所有生产、开发依赖全写在这个子文件里，让这个目录的依赖树和根目录的核心包完全物理隔离。
• 这种结构下，普通用户安装你的核心包时，npm根本不会遍历examples目录下的package.json，自然就不会安装任何演示相关的依赖。

3. 配置按需触发的演示依赖安装脚本 #

独立目录的依赖虽然隔离了，但本地开发总不能每次都手动切到examples目录下敲npm install，可以在根目录的package.json里加便捷脚本简化流程：

• 新增演示依赖安装脚本："setup:demo": "cd examples/react && npm install"，你本地第一次启动演示项目、或者拉取了新的演示依赖时，直接在根目录敲npm run setup:demo，就会自动进入演示目录安装专属依赖，完全不会污染根目录的依赖树
• 可以再配套加一个演示启动脚本："dev:demo": "cd examples/react && npm run dev"，实现根目录一键拉起演示项目，不用反复切换目录
• 这种方式刚好对应你提到的“仅在运行示例代码时才安装专属依赖”的需求，没有任何额外的配置魔法。

关于“专属触发安装依赖”的补充说明 #

很多人为了图方便会把演示依赖直接扔在根目录，再通过条件判断脚本触发安装，这种方案长期维护很容易出问题：

• 如果你硬要把演示依赖放在根目录，也可以把这部分依赖的安装逻辑单独拆成脚本，比如"install:demo-deps": "npm i -D react react-dom vite @vitejs/plugin-react"，但这种方式很容易把演示依赖混到根目录的锁定文件、根目录的node_modules里，时间长了依赖关系会越来越乱，远不如给演示项目单独建package.json干净。
• 千万别把演示依赖写成核心包的peerDependencies，不然用户安装你的核心包时，npm会直接弹出缺依赖的提示，完全打乱用户的项目配置。

常见踩坑提醒 #

• 一定要在根目录的.npmignore文件里加上examples/目录的忽略规则，和files字段形成双重保险，彻底避免示例代码被打包发布到NPM仓库
• 如果你用npm/yarn/pnpm的workspaces功能，不要把examples目录加进workspaces的配置列表，不然根目录的node_modules会把演示项目的依赖软链上来，虽然不会泄露给用户，但会让根目录的依赖树变得异常臃肿
• 本地调试的时候，不要在演示项目里用相对路径跨目录引用核心包的源码，直接用npm link把本地核心包链接到演示项目的依赖里，保持两边的依赖边界清晰

内容的提问来源于stack exchange，提问作者Bhavik Singh