使用 InvenTree Plugin Creator 快速搭建插件：安装、开发、构建与发布的完整实战指南

使用 InvenTree Plugin Creator 快速搭建插件安装、开发、构建与发布的完整实战指南【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTreeInvenTree 的开源插件体系十分强大且灵活但其复杂程度对新手开发者并不友好。本文以官方提供的inventree-plugin-creator命令行脚手架工具为主线完整讲解从安装工具、交互式创建插件、以可编辑模式安装到 InvenTree 实例、激活并调试前后端代码到最终编译前端资源、构建 Python 发行包并发布到 PyPI 的全流程。读完本文你将掌握一套可直接复用的 InvenTree 插件开发工作流并理解其背后的源码级实现原理mixin 注册机制、开发模式静态文件重定向、Vite manifest 哈希查找等。Plugin Creator 是什么为什么需要脚手架工具InvenTree 服务端通过可扩展的插件架构允许第三方功能直接嵌入安装实例从而在与核心代码解耦的前提下实现复杂行为参见 插件架构总览。插件可以来自多种渠道通过pip安装的第三方包放置于外部 plugins 目录的本地插件InvenTree 源码内置的 built-in 插件。然而插件的灵活与强大也意味着上手门槛较高一个合格插件通常需要同时编排 mixin 声明、包元数据、前后端静态资源、版本管理与 CI 配置。Plugin Creator 正是为此而生的命令行脚手架工具它让开发者快速生成一个带基础结构的插件骨架并在创建过程中通过交互式问答选择需要的功能特性。版本要求inventree-plugin-creator面向 InvenTree1.0.0 及以上版本设计。虽然它也能用于开发早期版本插件但生成器产生的用户界面UI相关特性在旧版本 InvenTree 中无法工作。工具提供的能力清单根据 creator.md该工具覆盖了插件开发的全生命周期元数据输入录入插件名称、描述、作者等元信息许可证选择提供多种许可证选项默认 MIT功能选择挑选需要包含的插件特性如各种 mixin 与前端功能DevOps 集成可选初始化 Git 版本控制、自动代码格式化基于 pre-commit、以及 GitHub / GitLab CI 集成部署支持生成可部署到 InvenTree 实例、可发布到 PyPI 的基础插件结构前端开发为前端特性搭建开发服务器支持热重载与构建工具链。前置要求开始之前需要满足两个条件拥有一套可正常运行的 InvenTree 实例已经按照官方 devcontainer 开发环境指南 搭建好开发环境本文示例采用 devcontainer 默认布局配置文件位于./dev/config.yaml。本文档示例全部使用 Plugin Creator 的默认选项你可以根据实际需求自定义各步骤的选择。安装 Plugin Creator工具通过 Python 包管理器分发执行pip install -U inventree-plugin-creator安装完成后命令行入口为create-inventree-plugin。创建插件交互式脚手架流程在终端中运行create-inventree-plugin命令会进入交互式引导流程依次完成以下配置。第一步插件元数据首先输入插件的元数据信息名称、描述、作者等。这一步直接对应插件类上的元数据属性——从源码看plugin.py 中的MetaBase基类通过get_meta_value()统一读取NAME/SLUG/TITLE等类属性并兼容PLUGIN_NAME等旧属性名使用旧名会触发 DeprecationWarning。其中SLUG未显式指定时会由名称自动 slugify 生成。第二步选择许可证为插件选择许可证默认 MIT也可选择其他常见开源许可证。许可证信息会被写入插件包的LICENSE文件并可作为类属性LICENSE提供给 InvenTree见 plugin.py 的license属性其回退读取包元数据中的 License 字段。第三步选择插件功能Mixin接下来选择要包含的插件 mixin 类型。InvenTree 后端定义了丰富的 mixin 枚举见 plugin.py 中的PluginMixinEnum包括但不限于action动作、api_call外部 API 调用、app自定义 App、barcode条码处理currencyexchange汇率、events事件监听、exporter数据导出、icon_pack图标包labels标签、locate定位、machine机器、mail邮件navigation导航、notification通知、report报表、schedule定时任务settings插件设置、settingscontent、supplier供应商数据、statetransition状态机urlsURL 路由、ui用户界面、validation数据校验、well-knownWell-Known 端点每个 mixin 通过MixinBase.add_mixin()注册进插件实例的_mixins字典并由mixin_enabled()判断是否启用、get_registered_mixins()提供注册信息查询见 plugin.py。若选择UserInterfaceMixin混入的是 ui/mixins.py 中定义的UserInterfaceMixin类其get_ui_features()按feature_type分发到spotlight_action、dashboard、panel、template_editor、template_preview、navigation、primary_action七类注入能力。第四步选择前端功能如果在上一步勾选了UserInterfaceMixin本例即是如此工具会继续询问要包含的前端功能Custom dashboard items为 InvenTree 用户界面创建自定义仪表盘组件Custom panel items向界面添加自定义面板Custom settings display为插件创建自定义设置页面。第五步Git 与 DevOps 集成可按需开启 Git 集成工具会初始化插件仓库并配置基于 pre-commit 的自动代码格式化还可以选择配置 CI 集成GitHub 或 GitLab让 CI 在代码推送后自动运行测试与检查。安装插件到 InvenTree可编辑模式创建完成后插件位于创建过程中指定的目录。以示例插件 MyCustomPlugin 为例验证生成的文件结构cd MyCustomPlugin ls -al典型目录结构如下实际文件取决于你在创建时勾选的功能文件 / 目录说明.git插件 Git 仓库选择 Git 集成时生成.githubGitHub 配置目录选择 GitHub 集成时生成.gitlab-ci.ymlGitLab CI 配置文件选择 GitLab 集成时生成.gitignoreGit 忽略规则文件.pre-commit-config.yamlpre-commit 钩子配置选择 pre-commit 时生成.editorconfig编辑器统一风格配置LICENSE插件许可证文件MANIFEST.in声明打包时需包含的文件README.md插件说明文档biome.jsonBiome 代码格式化器配置pyproject.toml插件项目配置setup.cfgPython 代码格式与 lint 规则setup.py插件安装脚本frontend/前端代码目录选择前端功能时生成my_custom_plugin/插件主目录目录名与创建时填写的插件名对应接下来需要在当前激活的 Python 环境中安装插件InvenTree 才能发现并加载它。开发阶段推荐使用editable install可编辑安装这样修改插件代码后无需重新安装即可生效pip install -e .安装后可用pip show验证pip show inventree-my-custom-plugin从源码角度看plugin.py 的is_editable()类方法通过检查{包名}-*.dist-info目录来判断插件是否为可编辑安装插件注册表据此识别本地开发插件。激活插件插件安装完毕后需要在 InvenTree 实例中将其激活。若服务器尚未运行先启动开发服务器invoke dev.server然后访问插件管理页面默认地址http://localhost:8000/web/settings/admin/plugin在插件列表中点击对应插件的Activate按钮完成激活。激活成功后插件即可参与 InvenTree 运行时流程。插件实例的激活状态由MetaBase.is_active()判定若插件被标记为 mandatory 则恒为激活否则查询PluginConfig.is_active()见 plugin.py。前端功能开发后端重定向与热重载本例创建的插件包含前端功能。生产环境中前端代码会被编译并以静态文件形式由 InvenTree 服务器托管但在开发阶段更实用的做法是运行一个提供热重载hot reloading的开发服务器。后端配置将静态请求重定向到开发服务器要让 InvenTree 后端把该插件的前端请求转发到开发服务器需要在服务器配置文件中添加以下配置使用默认 devcontainer 布局时为./dev/config.yamlplugin_dev: slug: my-custom-plugin # 替换为你的插件 slug host: http://localhost:5174注意修改配置文件后必须重启 InvenTree 服务器才能生效。这段配置让 InvenTree 将该插件的静态文件请求转发到 5174 端口上运行的开发服务器——该行为仅在开发模式下生效生产环境不会使用。其底层实现位于 settings.pyPLUGIN_DEV_SLUG读取配置键plugin_dev.slugPLUGIN_DEV_HOST读取plugin_dev.host默认值http://localhost:5174。随后 plugin.py 的plugin_static_file()在满足DEBUG开启、PLUGIN_DEV_HOST/PLUGIN_DEV_SLUG均已设置、且插件 slug 匹配这三个条件时会把资源 URL 拼接为{PLUGIN_DEV_HOST}/src/{path}并将.js扩展名替换为.tsx直接指向 Vite 开发服务器的源码文件。启动前端开发服务器进入frontend目录安装依赖并启动开发服务器cd frontend npm install npm run dev启动成功后开发服务器运行在 5174 端口验证查看自定义面板脚手架默认代码提供了一个显示在part 详情页上的自定义 panel。在 InvenTree 实例中打开任意零件详情页即可看到该自定义面板这一能力正是由UserInterfaceMixin的get_ui_panels()提供的。可以参考仓库内置示例 user_interface_sample.py面板通过key、title、source、icon、context字段描述其中source指向plugin_static_file()解析出的 JS 文件可带:renderFunction指定渲染函数context会把服务端数据如零件名、版本号、随机值传给前端渲染函数面板还可结合SettingsMixin的设置项和request.user.is_superuser按条件动态返回。编辑插件代码后端代码插件后端代码位于my_custom_plugin/目录主要逻辑集中在my_custom_plugin/core.py中。若创建时选择了其他 mixin 类型该目录下还会生成与之对应的额外文件。由于插件以可编辑模式安装修改后端代码后无需重新安装即可在 InvenTree 实例中立即生效。调试服务器说明后端代码的实时重载仅在 InvenTree 服务器以 debug 模式运行时有效生产模式下需重启服务器才能看到变更。前端代码前端代码位于frontend/src目录自定义 part 详情页面板实现在./frontend/src/Panel.tsx中可修改该文件调整面板内容与行为。开发服务器运行期间前端修改通过React Fast Refresh实时反映到浏览器无需每次重建前端。React Fast Refresh 注意事项插件模块中所有导出 React 组件的导出名必须以大写字母开头否则 React Fast Refresh 会退化为整页刷新此外任何被 Python 端引用的 render 函数名也必须大写。构建与发布插件上述流程面向开发阶段。开发完成后需要构建插件用于分发。CI 构建若在创建插件时配置了 CI 集成推送代码后 CI 服务器会自动构建插件这是推荐的构建与分发方式。编译前端资源前端资源在分发前必须先编译。编译产物主要是.js文件需要随插件一并分发由 InvenTree 服务器静态托管——因此编译文件需放入./my_custom_plugin/static目录前端build步骤会自动完成这一放置cd frontend npm run build后端在收集插件静态文件时会将每个插件的static目录复制到静态存储的plugins/{slug}/前缀下见 staticfiles.py。此外plugin.py 的hashed_file_lookup()支持读取插件静态目录中.vite/manifest.json由 Plugin Creator 前端框架生成从而定位带哈希文件名如file-abc123.js的资源以支持缓存破坏cache busting——这正是编译产物能够正确被引用的机制。构建 Python 包前端资源编译完成后即可构建可分发的 Python 包python -m build注意请在插件顶层目录即包含setup.py的目录中执行该命令。构建成功后会产出可供其他 InvenTree 实例安装的分发包。发布到 PyPI构建产物可发布到 PyPI或其他包索引使插件能被远程安装到其他 InvenTree 部署中。PyPI 发布细节不在本文范围内可参考 Python Packaging User GuidePython 打包用户指南中的打包项目教程。自动化发布若在创建插件时配置了 CI 集成当创建新 release 时 CI 服务器会自动将插件发布到 PyPI只需确保在 CI 环境中配置好必要的凭据。进一步阅读本文展示了插件开发的基础骨架。如需更复杂的开发示例可继续阅读 插件开发实战 Walkthrough该指南会带你逐步实现一个在零件详情页展示附件图片轮播的自定义面板可作为深入学习 InvenTree 插件前后端联调的进阶教程。【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考