插件目录结构

本章介绍常见的 JS 与 TS 插件包目录结构及作用，便于开发者快速理解和维护插件。

本章术语

• 📁 目录 = 文件夹
• 🗂️ 子目录 = 目录中的子文件夹

JS 插件包结构

以较为常见的 yenai-plugin 为例，插件基本目录结构如下：

plugin-files

插件由多个目录与文件组成，每个目录或文件都有明确的职责。

---

.github

用途：GitHub 专用目录

存放内容：

• GitHub Actions（CI/CD）
• issue / PR 模板
• 自动化脚本

与插件运行无关，仅用于项目管理和自动化。

---

apps 重点

功能入口

• 通常包含多个 JS 文件或子目录，每个文件对应一个完整的功能模块（功能单元）。
• 每个文件需导出 class，供 Yunzai 注册使用。
• 由 Yunzai 在加载插件时统一注册功能。

apps-files

---

components

可复用组件集合

• 存放配置组件、通用工具类、函数集合等，可被 apps 或其他模块复用。

components-files

---

config

配置文件目录

通常包含两个子目录：

• default_config：插件默认配置，由开发者维护，用户不应修改。
• config：用户可修改的配置，插件运行时优先读取。

分离默认配置与用户配置可以确保插件升级安全，降低维护成本。

config-files

---

constants

常量定义目录

• 存放不会或不应在运行时修改的值，如字符串常量、数组常量等。

constants-files

---

guoba 拓展

锅巴插件专用目录

• 用于支持 guoba-plugin，提供 Web 配置和信息展示。
• 拆分 guoba.support.js 进行模块化，方便维护。

guoba-files

---

lib

底层公共库

• 放置与具体业务逻辑无关的工具函数或核心逻辑。
• 与 components 相比更偏“底层”。

lib-files

---

model / modules

• model / models：数据模型或实体定义，描述数据字段、类型、默认值及关联关系。
• modules：功能模块或业务单元，实现具体业务逻辑，可复用 model、lib、components 中的能力。

yenai-plugin 将业务逻辑放在此处，对应 modules。

model-files

---

node_modules 自动生成

• 第三方依赖包目录，由 npm / pnpm / yarn 自动生成。
• 不应提交到版本库，一般加入 .gitignore。

---

resources

静态资源目录

• 存放图片、模板、字体、示例数据等非代码资源，运行时或打包时使用。

---

tool / utils

• tool：构建/开发/维护工具，如打包、迁移、代码生成脚本。
• utils：通用工具函数集合，如时间处理、格式化、校验、日志封装等。

在 yenai-plugin 中，tool 内容实际上属于 utils。

---

常见文件说明

文件名	说明
.all-contributorsrc	贡献者配置文件，用于自动生成贡献者列表
.eslintrc.cjs	ESLint 配置，规范代码风格与语法检查
.gitignore	Git 忽略规则，不提交到仓库
CHANGELOG.md	更新日志，记录版本变更
guoba.support.js	锅巴插件支持，提供 Web 配置
index.js	插件入口，将 apps 导出给 Yunzai 注册
LICENSE	开源协议，如 MIT / GPL / BSD
package.json	项目信息与依赖，👉 npm 官方文档说明
README.md	项目说明文档

---

TS 插件结构

TS 插件结构与 JS 插件类似，主要差别是源码位于 src，JS 文件由 TS 编译输出到 lib。

ts-plugin-tree

src

源码目录

• 存放 TS 源码，开发者在此编写代码。

---

lib

输出目录

• TS 编译后生成的 JS 文件，Yunzai 实际读取的插件内容。
• lib 保持与 src 相同目录结构。

---

index.js

Yunzai 入口兼容文件

• 指向 lib/index.js，用于兼容 Yunzai 加载。

---

src/types

类型定义目录

• 存放 TS 类型声明（interface、type、enum、全局类型扩展）。
• 用于约束数据结构与模块接口，无运行时逻辑。

---

src/dir.ts

路径常量

• 获取插件绝对路径，供模块引用。

---

src/index.ts

入口文件

• 集中导出 apps，供插件注册。