「pnpm add 明明成功了,为什么这个插件一点效果都没有?」 这个疑问把两个问题混在了一起:包是否安装,以及它的配置层是否被选中。在 DSH 中,这两件事在机制上彼此独立。
先说结论:成功执行 dsh plugin 操作后,CLI 会依据已安装依赖协调 profile 的 bundle 列表。 包要进入列表,必须带有 bundle 声明。
排查时常见的六种误区:
- 把包管理器成功当成能力已激活;
- 把普通依赖当成配置出错;
- 把仓库里源码有声明当成已安装产物也有;
- 把另一个 profile 有条目当成当前 profile 也应该有;
- 把列表里有名字当成每个插件都启动成功;
- 把别人的 registry 配置直接套到自己的环境。
记住这一点:包管理器执行成功,只能说明文件已写入磁盘,不能说明任何配置层已被组合进来。 站内基础版可参考 已安装插件没出现在 bundle 列表里。
一、包和 bundle 是两个概念
依赖即使安装成功,也可能不提供配置层。 这是设计如此,并非故障。
- bundle:在包清单中通过
dsh.bundle声明补丁的包; dsh.profile.bundles:profile 清单中的列表,决定这些层按什么顺序组合。
打包指南分别说明了作者提供的包清单和用户运行时使用的 profile 清单。弄清这两个文件各自的职责,后续排查会容易很多。
CLI 参考指出,没有 bundle 声明的依赖仍会作为普通依赖保留,并会触发一次性警告。
这一点很重要:警告不是报错,而是提示。
| 观察 | 含义 | 下一步 |
|---|---|---|
| 包已安装但无 bundle 声明 | 保留为普通依赖 | 确认作者是否打算提供配置层 |
| 源码包含声明 | 源码描述了 bundle | 检查实际安装的版本与产物 |
| 另一个 profile 有该条目 | 该 profile 选择了配置层 | 确认启动时使用的 profile |
| 运行期间安装了 bundle | 磁盘上的 bundle 集合发生变化 | 重启所选 profile |
二、安装器到底识别什么
打包指南中的包清单示例如下:
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml" } }
这里的补丁指向 bundle 的配置层;指南也将补丁文件列入发布文件。
关键是:仓库中有声明,并不保证当前安装版本和发布产物包含相同的清单及补丁。 因此,怀疑加载器之前,应先核对实际安装内容与作者发布的对应版本。
协调时机也需要注意:每次转发的包操作成功后,CLI 都会协调 profile 的 bundle 列表。更新后新增声明的包可以进入列表;被移除的依赖则会从列表中移除。
包管理器操作失败时,这个前提就不成立,列表也不会更新。此时应先处理包管理器错误,不要期待列表自行变化。
命令形态上有个易踩的坑
包管理命令必须将 profile 选项放在转发给包管理器的参数之前。CLI 文档中的例子是:
dsh plugin --profile <name> add <package>
另外,CLI 会在 profile 目录中将命令转发给 pnpm,因此路径中必须有 pnpm。
三、五步定位缺失条目
第一步,固定现场。 记录 DSH 版本、包名与版本、所选 profile、安装来源和完整警告。再次强调:包管理器执行成功,不代表能力已激活。
第二步,对照产物。 将实际安装产物与作者的声明核对,并检查对应补丁是否存在。如果作者只将它设计为普通依赖,不要自行补写 bundle 声明。
第三步,检查实际启动的 profile 清单。 CLI 的 profile 位于 $DSH_HOME/profiles/<name>。不同 profile 的依赖和 bundle 列表可能完全不同;这可能就是问题的全部原因。
第四步,比对来源与版本。 将失败安装所用的来源与已知产物对照,并记录双方的准确版本。只有证据指向相关配置且环境允许时,才调整 registry 配置。
第五步,重启并验证。 确认选中了正确的层后,重启 profile,查看启动诊断,并验证该 bundle 预期提供的能力。列表中有条目,并不能证明每个插件都已成功启动。
四、社区报告说明了什么,又没说明什么
在讨论 #10796中,一位用户报告:源码清单中虽有声明,安装时仍提示缺失;改从 GitHub 安装后则一切正常。
该用户将原因归结为 npm 配置中的 scope 映射指向 GitHub Packages,后者的元数据 API 不暴露自定义字段;用户称删除映射后问题解决。
应如何理解这段报告?它是针对特定版本和配置的用户报告,不能视为适用于所有 registry 的通用结论。
当前 CLI 参考将协调过程描述为基于已安装状态,但历史报告不能证明不同版本采用相同的内部检查方式。如果实际产物、profile 与警告彼此对不上,应保留证据并反馈给包或 DSH 维护者,不要直接照搬他人的修改。
包作者发布前该核对什么
包作者应检查消费者实际安装到手的产物。打包指南的示例将 JavaScript 入口和补丁都列入了 files。
这里对应两种不同的问题:
- 声明拼写正确,但指向的文件没被打进包里;
- 根本没有声明。
它们都可能表现为「没生效」,但修复方式完全不同。因此,应核对声明路径和产物内容,不能只复制清单片段。
两类清单别混用
包清单描述它提供什么补丁;profile 清单描述哪些 bundle 参与组合及其顺序。修改其中一个文件,不能证明另一个也已按预期更新。
五、架构和启动失败要分开归因
配置层可以插入插件行。但即使该层已被选中,其中某一行仍可能因自身依赖问题或启动失败而无法工作。
把这些层次分清,才能判断排查方向:
- 列表里没有它 → 查声明、产物、profile 选择;
- 列表里有了但没生效 → 查对应配置行和它的依赖服务;
- 列表里有了、启动也过了,某个能力仍不可用 → 查该能力自己的前置条件。
不要根据包管理器的成功信息推断运行状态,也不要因某项能力不可用就断言包未安装。 这两种错误推断都很常见。
更新和安装的差异
CLI 说明会在每次转发的包操作成功后进行协调,也包括更新后依赖新增 bundle 声明的情况。因此,升级包后新增一条 bundle 属于预期行为。
但从 Git 托管源安装源码包时,还有一个变量:CLI 指出 pnpm 10 及更高版本可能要求明确允许执行 prepare 构建。已构建 tarball 与本地 checkout 的文档行为不同。应按包管理器的实际提示操作,不要假设每次安装都需要相同的许可。
做来源对比时保持其他变量不变
尽量固定包版本和 profile,只更改来源。如果这些条件也发生变化,结果差异可能来自产物或配置组合,不能单独归因于来源。
记录来源配置的修改和恢复方法,尤其是该配置也会影响其他包时。
确认 bundle 已识别后,重启并验证预期功能。这样可以区分「列表协调」和「插件激活」,避免把后续依赖失败都归因于最初的警告。
六、限制与安全边界
安装 bundle 会引入代码和配置层。 安装前应检查来源、包身份及预期影响;列表中出现名称并不代表安全。
日志和配置可能包含 registry 凭据或私有包位置,分享前应先清理。
不要为了修正列表而重置 profile:CLI 的模板替换会删除自定义 profile 原有的依赖和用户补丁。为了修复一条列表项而清空整个 profile,代价不成比例。
最后,分别记录三种状态:安装成功、配置层被选择、能力正在运行。解析失败、依赖解析失败、schema 校验失败或插件启动失败,仍可能阻止启动。保留原始警告,围绕具体失败排查,尤其是在多个 bundle 同时参与组合时。
七、术语速查
- 包:已安装的依赖,可能提供 DSH 配置层,也可能不提供。
- Bundle:通过
dsh.bundle声明配置补丁的包。 - Profile:包含 bundle 列表和用户补丁的具名组合。
- 协调:包操作成功后,根据已识别的已安装依赖更新列表。
相关阅读
- 已安装插件没出现在 bundle 列表里
- 把本地插件 checkout 装进 profile
- 查某个 profile 为什么依赖某个插件
- pnpm 拦下 Git 插件的 prepare
- 插件更新后重启 profile
- 更多 DSH 实践文章
本文依据 DeepSeek Harness 打包指南、CLI 参考与社区讨论 #10796 整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/installed-plugin-missing-from-bundle
插件与文档收录于:https://dsh-plugin.com/zh/blog