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/nocobaseNocoBase 是一个开源的 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是导入第三方插件包的核心命令它支持三类来源来源示例说明远程压缩包https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz以http(s)://开头的下载地址CLI 会直接下载本地压缩包/your/path/plugin-auth-cas-1.4.0.tgz本机文件系统中的.tgz路径npm 包名或 tagmy-scope/plugin-auth-casbeta已发布到 npm registry 的包名可带版本或 dist-tag三种来源的命令形式# 远程压缩包 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-casbeta关键点这个命令只负责把插件包解压进storage/plugins不会自动启用插件。启用动作需要后续单独执行nb plugin enable。使用私有 npm 源如果插件发布在私有 npm registry 上通常来说先登录再通过--npm-registry指定源npm login --registryhttps://registry.example.com nb plugin import my-scope/plugin-auth-casbeta --npm-registryhttps://registry.example.com命令参数速查从nb plugin import的命令定义import.ts可以看到它支持以下参数参数/Flag类型说明archivestring必填插件来源本地.tgz路径、远程http(s)URL 或 npm 包 spec--env,-estring导入到哪个 CLI env省略时使用当前 env--yes,-yboolean显式--env指向非当前 env 时跳过交互确认默认 false--storage-pathstring覆盖 env 的 storage 根目录插件写入storage-path/plugins--npm-registrystring导入 npm 包 spec 时使用的 npm registry指定 storage 路径导入如果你已经知道目标应用的storage根目录例如拿到的是别人导出的 storage 目录或者要导入到尚未纳入 CLI 管理的应用可以不依赖当前 env直接传--storage-pathnb plugin import /your/path/plugin-auth-cas-1.4.0.tgz --storage-path ./storageCLI 会把插件写入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 envnb app restart -e app1nb app restartrestart.ts会停止并重新拉起应用本地local/git/npm环境走app:stopapp:start链路Docker 环境则会删除并重建保存的应用容器。重启是导入到生效之间不可或缺的一步因为应用只在启动阶段加载storage/plugins中的插件。重启之后再启用或验证第一次安装启用插件如果这是第一次安装该插件重启后再启用它nb plugin enable nocobase/plugin-auth-cas第一次启用时会自动完成插件的安装流程数据表、迁移等。nb plugin enableenable.ts支持一次启用多个插件nb plugin enable nocobase/plugin-a nocobase/plugin-b nb plugin enable -e local nocobase/plugin-sample启用命令的参数参数/Flag类型说明packages...string[]插件包名必填支持多个--env,-estringCLI env 名称省略时使用当前 env--yes,-yboolean显式--env指向非当前 env 时跳过交互确认补充说明只有当显式传入--env且目标与当前 env 不一致时CLI 才会弹出交互确认在非交互终端或 AI Agent 场景下需要显式追加--yes或先执行nb env use name再重试参见 enable.md。确认插件是否已出现在应用里想确认插件是否已经进入当前应用可以列出已安装插件nb plugin listnb plugin listlist.ts在本地/ Docker 环境等价于在应用内执行pm listHTTP 环境则回退到管理 API。升级插件时怎么做如果插件已经启用这次只是换成一个新版本通常来说只要两步导入新包 重启应用。nb plugin import /your/path/plugin-auth-cas-1.5.0.tgz nb app restart如果导入的是 npm 包也是一样nb plugin import my-scope/plugin-auth-caslatest 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 流程openPluginSourceplugin-import.ts按顺序判定参数属于哪类来源以http:/https:开头 → 远程 URL走 HTTP 下载携带认证跳转本地路径存在 → 本地.tgz文件直接读取以绝对路径、./、../开头或以.tgz/.tar.gz结尾但文件不存在 → 报错提示其余情况视为 npm 包 spec在临时目录执行npm pack --silent [--registry...] spec打包出 tarball 后再导入。npm 来源的npm pack调用带 30 秒超时并对三类典型失败给出可操作提示plugin-import.ts认证失败E401/E403/unauthorized 等→ 提示先执行npm login --registryregistry再重试包或 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 路径的解析优先级resolvePluginStoragePathplugin-storage.ts决定插件写入哪个目录优先级为传入的--storage-path或 env 配置中的 storagePath环境变量STORAGE_PATH在其下追加plugins子目录环境变量PLUGIN_STORAGE_PATH直接作为插件目录兜底默认./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已启用的插件升级只需importrestart导入动作检测到同名目录会直接整体替换。顺序很重要完整流程是「切 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考