NocoBase 第三方插件安装与升级：`nb plugin import` 全流程实战指南

NocoBase 第三方插件安装与升级：nb plugin import全流程实战指南

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

NocoBase 是一个开源的 AI + 无代码业务系统搭建平台，其插件机制允许你通过打包好的插件包扩展应用能力。当你从社区、私有仓库或合作伙伴处拿到一个第三方插件包时，本文所讲解的安装与升级流程就是标准的操作路径：把插件导入到目标应用的storage/plugins目录、重启应用、再启用或验证插件。读完本文，你将掌握nb plugin import支持的三种导入来源（远程压缩包、本地压缩包、npm 包）、--storage-path的离线导入方式、升级已启用插件的正确姿势，以及导入底层源码原理。

先确认目标环境

如果你本地通过nbCLI 管理了多个应用（env），第一步是先切换到目标 env，确保后续导入、重启、启用操作都作用在正确的应用上：

nb env use app1

切换后，后续的nb plugin import、nb app restart、nb plugin enable都会默认作用于app1。如果你不想切换当前 env，也可以在命令里显式传入-e <env>指定目标（见下文各命令的参数说明）。

用nb plugin import导入插件包

nb plugin import是导入第三方插件包的核心命令，它支持三类来源：

三种来源的命令形式：

# 远程压缩包 nb plugin import https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz # 本地压缩包 nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz # npm 包名或 tag nb plugin import @my-scope/plugin-auth-cas@beta

关键点：这个命令只负责把插件包解压进storage/plugins，不会自动启用插件。启用动作需要后续单独执行nb plugin enable。

使用私有 npm 源

如果插件发布在私有 npm registry 上，通常来说先登录，再通过--npm-registry指定源：

npm login --registry=https://registry.example.com nb plugin import @my-scope/plugin-auth-cas@beta --npm-registry=https://registry.example.com

命令参数速查

从nb plugin import的命令定义（import.ts）可以看到它支持以下参数：

指定 storage 路径导入

如果你已经知道目标应用的storage根目录（例如拿到的是别人导出的 storage 目录，或者要导入到尚未纳入 CLI 管理的应用），可以不依赖当前 env，直接传--storage-path：

nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz --storage-path ./storage

CLI 会把插件写入<storage-path>/plugins。这种情况下可以不先执行nb env use，也可以不传--env——storage 路径直接由该 flag 决定，与 env 无关。从实现看，--storage-path的优先级高于 env 自带的 storage 路径（import.ts 中storagePath = storagePathOverride || runtimeForDefaults?.env.storagePath）。

导入之后先重启

导入完成后，先重启目标应用，让应用重新扫描并加载插件目录：

nb app restart

如果你没有先切换当前 env，也可以显式传-e <env>：

nb app restart -e app1

nb app restart（restart.ts）会停止并重新拉起应用：本地（local/git/npm）环境走app:stop+app:start链路，Docker 环境则会删除并重建保存的应用容器。重启是导入到生效之间不可或缺的一步，因为应用只在启动阶段加载storage/plugins中的插件。

重启之后再启用或验证

第一次安装：启用插件

如果这是第一次安装该插件，重启后再启用它：

nb plugin enable @nocobase/plugin-auth-cas

第一次启用时会自动完成插件的安装流程（数据表、迁移等）。nb plugin enable（enable.ts）支持一次启用多个插件：

nb plugin enable @nocobase/plugin-a @nocobase/plugin-b nb plugin enable -e local @nocobase/plugin-sample

启用命令的参数：

补充说明：只有当显式传入--env且目标与当前 env 不一致时，CLI 才会弹出交互确认；在非交互终端或 AI Agent 场景下，需要显式追加--yes，或先执行nb env use <name>再重试（参见 enable.md）。

确认插件是否已出现在应用里

想确认插件是否已经进入当前应用，可以列出已安装插件：

nb plugin list

nb plugin list（list.ts）在本地/ Docker 环境等价于在应用内执行pm list，HTTP 环境则回退到管理 API。

升级插件时怎么做

如果插件已经启用，这次只是换成一个新版本，通常来说只要两步：导入新包 + 重启应用。

nb plugin import /your/path/plugin-auth-cas-1.5.0.tgz nb app restart

如果导入的是 npm 包，也是一样：

nb plugin import @my-scope/plugin-auth-cas@latest nb app restart

也就是说，升级场景不需要再额外执行nb plugin enable——把新包导入进去，然后重启应用即可。从源码看，当storage/plugins下已存在同名插件目录时，导入会以updated动作处理：先删除旧目录再放入新内容（plugin-import.ts 中action = (await pathExists(outputDir)) ? 'updated' : 'installed'），因此旧版本的残留文件会被干净替换，这也是为什么升级不需要先手动禁用或卸载。

不能直接联网时

如果目标机器不能直接访问插件下载地址（如远程压缩包 URL 或 npm registry 都不可达），可以先把.tgz文件上传到目标机器的任意目录，再在目标机器执行本地导入：

nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz nb app restart

:::warning 注意 这里不需要手动解压到storage/plugins。nb plugin import会自动完成解压并放到正确目录：它会先把压缩包解压到storage/plugins下的临时暂存目录，解析出插件包名后，再把包根目录移动（rename）到<storage/plugins>/<包名>的最终位置（plugin-import.ts）。 :::

深入：nb plugin import的底层工作原理

为了让上面的操作更可预期，这里结合仓库源码补充几个实现层面的细节：

来源判定与 npm pack 流程

openPluginSource（plugin-import.ts）按顺序判定参数属于哪类来源：

1. 以http:/https:开头 → 远程 URL，走 HTTP 下载（携带认证跳转）；
2. 本地路径存在 → 本地.tgz文件，直接读取；
3. 以绝对路径、./、../开头或以.tgz/.tar.gz结尾但文件不存在 → 报错提示；
4. 其余情况视为 npm 包 spec，在临时目录执行npm pack --silent [--registry=...] <spec>打包出 tarball 后再导入。

npm 来源的npm pack调用带 30 秒超时，并对三类典型失败给出可操作提示（plugin-import.ts）：

• 认证失败（E401/E403/unauthorized 等）→ 提示先执行npm login --registry=<registry>再重试；
• 包或 tag 不存在（E404/ETARGET/not found 等）→ 提示检查包名或 tag 是否正确；
• 网络不可达（ENOTFOUND/ETIMEDOUT/ECONNREFUSED 等）→ 提示检查 registry 是否可达。

这些行为都有对应的测试用例覆盖，见 plugin-import.test.ts。

包名安全校验与目录布局

导入时会读取压缩包内package.json的name字段作为插件包名，并对包名做路径穿越防护：解析出的目标目录如果越出插件存储根目录（以..开头等）会直接报错。最终目录布局遵循 npm scope 惯例，例如@nocobase/plugin-auth-cas会被放到：

<storage>/plugins/@nocobase/plugin-auth-cas/

这与测试中断言的输出路径一致（plugin-import.test.ts 中outputDir为path.join(storage, 'plugins', '@nocobase', 'plugin-demo')）。

storage 路径的解析优先级

resolvePluginStoragePath（plugin-storage.ts）决定插件写入哪个目录，优先级为：

1. 传入的--storage-path（或 env 配置中的 storagePath）；
2. 环境变量STORAGE_PATH（在其下追加plugins子目录）；
3. 环境变量PLUGIN_STORAGE_PATH（直接作为插件目录）；
4. 兜底默认./storage/plugins（相对当前工作目录）。

了解这条链路，有助于排查"插件到底装到哪里去了"的问题。

环境类型的限制

从源码看，nb plugin import目前对HTTP 环境（仅 API 连接）和 SSH 环境不支持导入：HTTP 环境不暴露可写的本地storage/plugins路径，SSH 环境支持保留但尚未实现。本地（local/git/npm）和 Docker 环境是当前支持导入的两种方式。如果你管理的是远程 API 环境，需要在其宿主机上用本地或 Docker 方式完成导入。

常见问题与注意事项

• 导入不等于启用：nb plugin import只把包放进storage/plugins，第一次使用还要nb plugin enable，首次启用时会自动完成安装。
• 升级不需要重新 enable：已启用的插件升级只需import+restart，导入动作检测到同名目录会直接整体替换。
• 顺序很重要：完整流程是「切 env → import → restart → enable（首次）→ 验证」。跳过 restart 直接启用，应用可能还看不到新插件。
• 离线导入时别手动解压：上传.tgz后交给nb plugin import，它会自动处理解压与目录安置，手动解压反而可能放错位置。
• 非交互场景记得--yes：显式--env指向非当前 env 时，交互终端会确认；自动化脚本或 Agent 场景需追加--yes。

相关命令参考

• nb app restart：重启选中 env 的应用
• nb plugin enable：启用一个或多个插件
• nb plugin list：列出选中 env 已安装的插件

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase