NocoBase 插件依赖管理全局依赖、peerDependencies 与构建打包策略详解【免费下载链接】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 插件的依赖分为「自身依赖」与「全局依赖」两类二者的划分直接决定了插件产物体积、运行时是否出现版本冲突以及开发与生产环境是否一致。本文基于 NocoBase 官方插件开发文档《依赖管理》结合仓库中示例插件的真实package.json声明与构建打包流程完整讲解依赖声明的原则、全局依赖清单的完整列表以及如何在devDependencies/peerDependencies之间做出正确取舍帮助你在发布插件前避免「本地能跑、装到别人环境就冲突」的典型问题。一、核心概念自身依赖与全局依赖在 NocoBase 插件开发中所有依赖被划分为两类全局依赖由 NocoBase 运行时nocobase/server与nocobase/client-v2统一提供。插件中引用这些包时不需要也不应该把它们单独打包进插件产物。自身依赖插件独有的依赖包括 server 端依赖。这类依赖会被打包到插件产物中其中 server 端依赖会进入dist/node_modules目录随插件一起分发。理解这个划分是后面所有策略的前提既然自身依赖会被打进产物那么「哪些依赖该由宿主提供、哪些该由插件自带」就决定了最终.tgz包的体积与隔离性。二、开发原则优先用 devDependencies而不是 dependencies文档给出的核心原则是由于自身依赖会被打包到插件产物中server 依赖会打包到dist/node_modules你可以将所有依赖声明在devDependencies中而不是dependencies。这样可以避免开发环境与生产环境产生差异。这条原则的底层逻辑是产物才是分发单位。NocoBase 插件最终通过yarn build构建、yarn nocobase tar打包成.tgz分发见 构建与打包构建时会把dependencies中声明的运行时依赖一并收集进dist/node_modules。devDependencies 只在开发期安装不会触发「开发环境与最终产物依赖树不一致」的问题如果插件作者把本该打包的依赖漏在dependencies之外或者错误地写进peerDependencies本地调试时可能恰好被宿主版本“代偿”上线后却找不到实现。官方示例插件的package.json正是这一原则的落地。以仓库中的简单块示例插件为例plugin-simple-block/package.json 的完整声明为{ private: true, name: nocobase-example/plugin-simple-block, displayName: Plugin example: Simple block, description: This plugin demonstrates how to use the simple block feature to create a simple block., version: 2.2.13, main: dist/server/index.js, devDependencies: { big.js: 7.0.1 }, peerDependencies: { nocobase/client: 2.x, nocobase/client-v2: 2.x, nocobase/server: 2.x, nocobase/test: 2.x } }从这份真实配置可以看到两点与文档原则完全吻合的写法插件自身独有的big.js声明在devDependencies中构建时会被打包进产物对 NocoBase 核心的依赖nocobase/server、nocobase/client-v2、nocobase/test等统一声明在peerDependencies中并锁定到2.x大版本表达「这些由宿主 NocoBase 提供我只要求主版本兼容」的契约而不是要求 npm 再安装一份。因此一个可参考的声明范式是{ devDependencies: { 某个插件独有的库: 具体版本 }, peerDependencies: { nocobase/server: 2.x, nocobase/client-v2: 2.x } }三、全局依赖完整清单这些包由 NocoBase 提供无需打包以下是官方文档列出的全局依赖完整列表。插件中若使用到其中任何一个都应与 NocoBase 的版本保持一致不要自行安装不同版本// nocobase 核心 nocobase/acl, nocobase/actions, nocobase/auth, nocobase/cache, nocobase/client-v2, nocobase/database, nocobase/evaluators, nocobase/logger, nocobase/resourcer, nocobase/sdk, nocobase/server, nocobase/test, nocobase/utils, // nocobase/auth jsonwebtoken, // nocobase/cache cache-manager, cache-manager-fs-hash, // nocobase/database sequelize, umzug, async-mutex, // nocobase/evaluators formulajs/formulajs, mathjs, // nocobase/logger winston, winston-daily-rotate-file, // koa 生态 koa, koa/cors, koa/router, multer, koa/multer, koa-bodyparser, koa-static, koa-send, // React 生态 react, react-dom, react/jsx-runtime, // React Router react-router, react-router-dom, // Ant Design antd, antd-style, ant-design/icons, ant-design/cssinjs, // i18n i18next, react-i18next, // dnd-kit dnd-kit/accessibility, dnd-kit/core, dnd-kit/modifiers, dnd-kit/sortable, dnd-kit/utilities, // Formily formily/antd-v5, formily/core, formily/react, formily/json-schema, formily/path, formily/validator, formily/shared, formily/reactive, formily/reactive-react, // 通用工具 dayjs, mysql2, pg, pg-hstore, supertest, axios, emotion/css, ahooks, lodash,清单的分组结构本身传递了重要信息——这些包并非 NocoBase 额外“赠送”的第三方库而是各核心包的传递依赖由宿主统一持有分组提供来源典型用途nocobase/*核心NocoBase 核心包ACL、认证、数据库、日志、资源路由、测试工具等koa 生态koa、koa/router、koa-bodyparser等nocobase/server服务端中间件与请求处理React / Ant Design / Formily / dnd-kit 生态nocobase/client-v2客户端 UI、表单与拖拽能力数据库驱动pg、mysql2、pg-hstorenocobase/databasePostgreSQL / MySQL 连接sequelize、umzug、async-mutexnocobase/databaseORM、迁移与并发控制这一结构与仓库源码目录一一对应packages/core/database、packages/core/logger、packages/core/resourcer等核心包分别提供上表中的能力插件在src/server中import这些包时实际解析到的是宿主安装的同一份实例——这正是「避免重复打包、避免双实例冲突」的关键。四、三条开发建议及其原理官方文档给出了三条开发建议逐条拆解如下1. 保持依赖一致性如果全局依赖中已经有某个包直接用全局版本就好不要安装不同版本。插件中用到下列依赖时确保版本号与全局依赖中nocobase/server和nocobase/client-v2保持一致否则可能导致运行时冲突。典型风险是React 类库插件自带一份react18.x宿主是另一份useContext/ hooks 跨两份 React 实例调用会直接抛错ORM 类库自带sequelize与宿主版本不一致时模型元数据、方言处理可能出现微妙差异状态与样式库lodash、dayjs这类重复打包不会报错但会白白增加产物体积。2. 尽量减少打包体积常见的 UI 库比如antd、工具库比如lodash、数据库驱动比如pg、mysql2都应该用全局提供的版本避免重复打包。antd、lodash单包体积都不小mysql2、pg还涉及原生可选依赖。由于自身依赖会被打包进dist/node_modules随.tgz分发重复携带这些包会显著增大插件体积并拉长其他环境的安装时间。判断标准很简单在全局依赖清单里有的一律不打包。3. 调试与生产环境一致用devDependencies即可保证开发与最终产物一致避免因dependencies与peerDependencies配置不当导致的环境差异。这条建议呼应第二节的原则把可打包依赖统一放进devDependencies把宿主契约放进peerDependencies如 plugin-simple-block 中对nocobase/server: 2.x的声明让本地开发、CI 构建和最终产物三者看到同一套依赖树从源头消除「环境差异」类故障。五、依赖声明与构建打包的衔接依赖声明的正确性只有在完整走一遍构建打包流程后才真正落地# 构建客户端代码由 Rsbuild 打包服务端代码由 tsup 打包 yarn build my-project/plugin-hello # 打包生成 storage/tar/my-project/plugin-hello-0.1.0.tgz yarn nocobase tar my-project/plugin-hello # 或一步完成 yarn build my-project/plugin-hello --tar构建时会执行依赖收集devDependencies中声明的自身依赖被收集进dist/node_modulesserver 端或打进客户端 bundle而peerDependencies声明的nocobase/*核心包则保持为运行时引用、由目标 NocoBase 应用提供。因此如果某个全局依赖包被误写进dependencies它会被重复打包产物膨胀且存在双实例风险如果某个真正的自身依赖漏声明构建产物中不会包含它插件在其他环境加载时才会暴露Cannot find module错误。上传.tgz到目标应用的./storage/plugins目录或nb plugin import后插件在「插件管理器」中手动开启即可生效详细流程见 构建与打包 与 安装与升级插件。六、小结一张判定表拿到一个依赖时按以下顺序决策它在全局依赖清单里吗→ 是不安装、不打包直接import如需要在package.json中留痕用peerDependencies声明版本区间如2.x。它是插件独有的吗→ 是声明在devDependencies中并锁定具体版本构建时自动打包进产物。构建后验证→ 执行yarn build --tar检查dist/node_modules中是否只有预期的自身依赖、.tgz体积是否符合预期。这套「全局依赖 devDependencies peerDependencies 版本契约」的组合就是 NocoBase 插件依赖管理的完整闭环它既保证了插件与宿主运行时的版本一致性又把隔离性留在了真正需要隔离的部分。相关链接构建与打包 — 插件的构建与打包配置项目目录结构 — 插件的文件组织方式编写第一个插件 — 从零开始创建插件插件开发概述 — 插件开发整体介绍【免费下载链接】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），仅供参考