dsh plugin add 本地目录怎么装？git clone 源码、npm 与市场安装怎么选

dsh plugin add 加本地目录一条命令装进 profile：git clone 仓库后 add ../仓库目录；GitHub 源码源只拉源码不拉构建产物，要 author 的 prepare 脚本与用户 allowBuilds 授权；最后给 npm 版与官方市场的选择建议。

本文转自 DSH Plugin Hub 插件市场

dsh plugin add 加本地目录就一条命令：git clone 插件仓库后，在仓库所在目录运行 dsh plugin --profile web add ./插件目录，pnpm 会把它链接进 profile。GitHub 源码源（github:owner/repo）装的是源码不是构建产物——需要作者提供 prepare 构建脚本、用户再把包名加进 allowBuilds 白名单（pnpm 10+ 默认拒绝执行）；图省心选 npm 版或走 DSH Plugin Hub 插件市场。本文按官方教程展开三种安装方式的选择。

概览

一句话：本地目录安装是调试插件最直接的方式，dsh plugin add 转发给 pnpm，pnpm 支持的一切写法 dsh 都支持。 官方教程《打包与安装插件》从零演示了 bundle 概念、add ./hello-plugin 本地目录安装、github:you/hello-plugin 源码安装与 build-script 坑（来源）。下面按三种方式展开。

本地目录安装：git clone 后 add 一条命令

本地目录安装 = 把插件源码目录直接链接进 profile，改完即生效、最适合调试。 官方教程的完整流程（12345）：

1. 准备插件包目录，里面至少有 package.json（声明 dsh.bundle 才有配置层）与插件入口文件。想拿现成源码调试，先克隆仓库：

   git clone https://github.com/你/插件仓库.git
   cd 插件仓库
   

2. 在包含插件包的目录里运行 add，参数直接指向插件目录：

   dsh plugin --profile web add ./插件目录
   

   官方例子是 dsh plugin --profile demo add ./hello-plugin（来源）。首次运行会初始化 profile，pnpm 把目录以 link: 依赖链接进去；包声明了 dsh.bundle 时，dsh 自动把它追加到 dsh.profile.bundles。
3. 不用启动先验证配置层：

   dsh --profile web --dump-config
   

   输出里能看到 # == 插件名 那一层，说明配置层已生效。
4. 启动确认插件加载：

   dsh --profile web
   

5. 以后改目录里的源码，重启 Web UI 即可看到新行为。

注意：dsh.profile 是 dsh plugin 创建并维护的，官方明确说不要手写（来源）。

GitHub 源码安装：不拉构建产物的坑、prepare 与 allowBuilds

github:owner/repo 装的是源码不是构建产物——TypeScript 包装完没有 lib/ 输出，直接加载失败，这是 GitHub 源码安装最大的坑。 要修好需要两边各做一件事（来源）：

1. 作者侧：提供 prepare 脚本。pnpm 在 git 安装后会运行它来从源码构建发布入口，脚本要自包含（不能依赖 monorepo 兄弟目录等开发环境）。官方例子 turtle-ui 用独立 tsdown 配置把 src/ 转译出来，不依赖项目引用与类型检查。
2. 用户侧：给构建脚本授权。pnpm 10 及以上默认拒绝运行 git 依赖的 prepare 脚本，所以第一次 add 会失败——dsh 会指向修复方法：把 pnpm 打印的包名抄进 profile 的 pnpm-workspace.yaml：

   allowBuilds:
     插件包名: true
   

   然后重新执行 add。

把 allowBuilds 当成它本来的意思：授权在安装时于本机执行该包的代码（不进沙箱）。只给源码可信的包授权，并把版本钉死到 commit（github:owner/repo#sha），防止后续推送悄悄改变要执行的代码（来源）。

与 npm 版、官方市场怎么选

不想跟用户要构建授权的，就分发构建产物——npm 版或 tarball 都不需要任何构建授权。 三条选择建议：

1. 改源码调试 → 本地目录 add ./目录 最快，改完重启即生效。
2. 装现成插件 → 优先 npm 版：dsh plugin --profile web add 包名，包在 pnpm publish 时已带好 lib/ 构建产物；或让作者给 pnpm pack 的 tarball，dsh plugin add ./插件-0.1.0.tgz 本地文件装（来源）。
3. 可视化安装与更新 → 打开 Web UI 的「设置 → 插件市场」，即社区插件市场 DSH Plugin Hub，按分类浏览、一键安装/升级/卸载，比命令行省心。

注意事项

1. dsh plugin 把参数原样转发给 pnpm，add ./目录、add 包名、add github:owner/repo、add ./包.tgz 都走同一条通道（来源）。
2. GitHub 源码源装的是源码，包没有 prepare 脚本就装完缺构建产物、加载失败——装前确认作者是否分发构建产物。
3. pnpm 10+ 默认拒绝 git 依赖的构建脚本，allowBuilds 白名单放行前先确认源码可信。
4. 有条件就 pin commit（github:owner/repo#sha），让安装内容可复现。
5. 没有 dsh.bundle 声明的包能装但不能激活配置层，dsh plugin 会打警告（来源）。
6. 本地调试确认可用后，把插件提交到 DSH Plugin Hub 收录，让更多人直接用上。

常见问题

dsh plugin add 可以加本地目录吗？

可以。dsh plugin 子命令把参数原样转发给 pnpm，pnpm 原生支持安装本地目录：git clone 插件仓库后，在含插件包的目录里运行 dsh plugin --profile web add ./插件目录（官方教程用 add ./hello-plugin），pnpm 会把目录链接进 profile 的依赖，声明了 dsh.bundle 的包还会自动追加进 bundles 列表。

本地目录装完怎么验证成功？

两步：先 dsh --profile web --dump-config，能看到 # == 插件名 那一层说明配置层已生效；再 dsh --profile web 启动，日志里出现插件加载信息。不用重启前先去设置 → 插件市场确认已出现在已安装列表。

为什么 dsh plugin add github:owner/repo 第一次总是失败？

git 安装拉的是源码而不是构建产物，源码包的 prepare 构建脚本默认不执行。pnpm 10 及以上拒绝运行 git 依赖的 prepare 脚本，第一次 add 会失败；把 dsh 提示的包名写进 profile 的 pnpm-workspace.yaml 的 allowBuilds 白名单后再跑一次 add 就好。

allowBuilds 授权安全吗？

它等于授权在安装时执行该包的代码，而不是进沙箱执行。只给信得过的源码授权，并把版本钉死到 commit（github:owner/repo#sha），防止作者后续推送悄悄改掉要执行的代码。官方明确提示把它当执行许可看待。

本地目录、GitHub 源码和 npm 版怎么选？

改源码调试选本地目录 add ./目录 最快；只是想装没构建产物的仓库选 GitHub 源，但要 prepare + allowBuilds；想要省心选 npm 版（pnpm publish 时已带构建产物，一条 add 包名 搞定）；想可视化安装与更新，直接走 DSH Plugin Hub 的插件市场。

本文转自 DSH Plugin Hub 插件市场，版权归属 DSH Plugin Hub 插件市场。

分类：插件开发

原文地址：https://dsh-plugin.org/zh/tutorials/install-plugin-local-dir

首页：DSH Plugin Hub

来源：打包与安装插件（官方教程）、turtle-ui（prepare 脚本示例）