发布插件

为了让别人更方便地使用你编写的插件，你需要将其作为一个 npm 包进行发布。只需满足一定的规范，你的插件就能显示在插件市场中，其他人可以通过控制台来安装它。

TIP

本节中介绍的命令行都需要在应用目录下运行。

准备工作

首先让我们关注插件目录中的 package.json 文件。这个文件非常重要，它包含了要发布插件的一切元信息。

diff

root
├── plugins
│   └── example
│       ├── src
│       │   └── index.ts
│       └── package.json        # 你应该修改这里
├── koishi.yml
└── package.json                # 而不是这里

TIP

请注意 package.json 文件不是唯一的，它在应用目录和每个插件目录都会存在。请确保你修改了正确的文件。

打开上述文件，你会看到它大概长这样：

package.json

{
  "name": "koishi-plugin-example",
  "version": "1.0.0",
  // ……
}

其中最重要的属性有两个：name 是要发布的包名，version 是当前版本号。可以看到，这里的包名相比实际在插件市场中看到的插件名多了一个 koishi-plugin- 的前缀，这使得我们很容易区分 Koishi 插件与其他 npm 包，同时也方便了用户安装和配置插件。

TIP

请注意：包名和版本号都是唯一的：包名不能与其他已经发布的包相同，而同一个包的同一个版本号也只能发布一次。如果出现了包名冲突或版本号冲突，则会在之后的发布流程中出现错误提示。你可以自行根据错误提示更改包名或更新插件版本。

补充更多信息

除了包名和版本号以外，package.json 还包括了插件的依赖、描述、贡献者、许可证、关键词等更多信息。你并不需要一上来就把所有信息都填写完整，因为你可以随后再进行修改。但请别忘了，这些内容也是插件的一部分，修改完成后别忘了更新版本并再次发布。

准入条件

TIP

使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。

要想显示在插件市场中，插件的 package.json 需要满足以下基本要求：

name 必须符合以下格式之一：
- koishi-plugin-*
- @bar/koishi-plugin-*
- @koishijs/plugin-* (官方插件)
- 其中 * 是由数字、小写字母和连字符 - 组成的字符串
name 不能与已发布的插件重复或相似
version 应当符合语义化版本 (通常从 1.0.0 开始)
peerDependencies 必须包含 koishi
不能声明 private 为 true (否则你的插件无法发布)
最新版本不能被弃用

一个符合上述标准的示例：

package.json

{
  "name": "koishi-plugin-example",
  "version": "1.0.0",
  "peerDependencies": {
    "koishi": "^4.3.2"
  }
}

添加相关信息

除去上面的基本要求外，package.json 中还有一些字段能帮助显示插件的相关信息。

package.json

{
  "name": "koishi-plugin-example",
  "version": "1.0.0",
  "contributors": [                         // 贡献者
    "Alice <alice@gmail.com>",
    "Bob <bob@gmail.com>"
  ],
  "license": "MIT",                         // 许可证
  "homepage": "https://example.com",        // 主页
  "repository": {                           // 源码仓库
    "type": "git",
    "url": "git+https://github.com/alice/koishi-plugin-example.git"
  },
  "keywords": ["example"],                  // 关键词
  "peerDependencies": {
    "koishi": "^4.3.2"
  }
}

contributors: 插件维护者，应该是一个数组，其中的元素通常使用 名字 <邮箱> 的格式
license: 插件许可证，你可以在这里了解各种许可证的详细信息
homepage: 插件主页，可以是一个网址 (比如你的 GitHub 项目地址)
repository: 插件源码仓库，应该是一个对象，其中 type 字段指定仓库类型，url 字段指定仓库地址
keywords: 插件关键词，应该是一个字符串数组，会用于插件市场中的搜索功能

TIP

package.json 中还有一些字段没有在这里提及，如果你对此感兴趣，可以前往 npmjs.com 查看文档。

`koishi` 字段

除此以外，我们还提供了一个额外的 koishi 字段，用于指定与 Koishi 相关的信息。

package.json

{
  "name": "koishi-plugin-dialogue",
  "version": "1.0.0",
  "peerDependencies": {
    "koishi": "^4.3.2"
  },
  "koishi": {
    "description": {                        // 不同语言的插件描述
      "en": "English Description",
      "zh": "中文描述"
    },
    "service": {
      "required": ["database"],             // 必需的服务
      "optional": ["assets"],               // 可选的服务
      "implements": ["dialogue"],           // 实现的服务
    },
  }
}

description: 插件描述，应该是一个对象，其中的键代表语言名，值是对应语言下的描述
service: 插件的服务相关信息，详情请参见服务与依赖
preview: 配置为 true 可以让插件显示为「开发中」状态
hidden: 配置为 true 可以让插件市场中不显示该插件 (通常情况下你不需要这么做)

TIP

此外，还有一些字段与 Koishi Online 的部署流程相关 (如 browser, exports 等)。由于不影响主线开发，你可以稍后再进行了解。

发布插件

编辑完上面的清单文件并构建源代码后，你就可以公开发布你的插件了。

npm

npm run pub [...name]

name: 要发布的插件列表，缺省时表示全部 (此处 name 不包含 koishi-plugin- 前缀，而是你的工作区目录名)

这将发布所有版本号发生变动的插件。

TIP

从插件成功发布到进插件市场需要一定的时间 (通常在 15 分钟内)，请耐心等待。

TIP

如果你配置了国内镜像，你可能会遇到以下的错误提示：

text

No token found and can't prompt for login when running with --non-interactive.

此时你需要在发布时使用官方镜像，具体操作如下：

npm

npm run pub [...name] -- --registry https://registry.npmjs.org

对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像：

yarn

# 安装时使用国内镜像
yarn config set npmRegistryServer https://registry.npmmirror.com
# 发布时使用官方镜像
yarn config set npmPublishRegistry https://registry.yarnpkg.com

更新插件版本

初始创建的插件版本号为 1.0.0。当你修改过插件后，你需要更新版本号才能重新发布。在应用目录运行下面的命令以更新版本号：

npm

npm run bump [...name] -- [-1|-2|-3|-p|-v <ver>] [-r]

name: 要更新的插件列表，不能为空
-1, --major: 跳到下一个大版本，例如 3.1.4 -> 4.0.0
-2, --minor: 跳到下一个中版本，例如 3.1.4 -> 3.2.0
-3, --patch: 跳到下一个小版本，例如 3.1.4 -> 3.1.5
-p, --prerelease: 跳到下一个预览版本，具体行为如下
- 如果当前版本是 alpha.x，则跳到 beta.0
- 如果当前版本是 beta.x，则跳到 rc.0
- 如果当前版本是 rc.x，则移除 prerelease 部分
- 其他情况下，跳到下一个大版本的 alpha.0
-v, --version: 设置具体的版本号
-r, --recursive: 递归更新依赖版本
缺省情况：按照当前版本的最后一位递增

当进行此操作时，其他相关插件的依赖版本也会同步更新，确保所有工作区内依赖的插件版本一致。进一步，如果你希望更新了依赖版本的插件也同时更新自身的版本，那么可以附加 -r, --recursive 选项。

弃用插件

如果你不再维护某个插件，或者你希望更换一个名字重新发布，那么你可以弃用该插件。在任意目录运行下面的命令以弃用插件：

npm deprecate <full-name> <message>
# 例如
npm deprecate koishi-plugin-example "this plugin is deprecated"

请注意这里要写出的是完整的包名，而不是插件的目录名。

你也可以弃用某个特定版本或版本区间 (默认情况下将弃用所有版本)：

npm deprecate <full-name>[@<version>] <message>

弃用插件的最新版本后，该插件将不再显示在插件市场中。未来你仍然可以发布新版本，这将使你的插件重新进入插件市场。

发布插件 ​

准备工作 ​

补充更多信息 ​

准入条件 ​

添加相关信息 ​

koishi 字段 ​

发布插件 ​

更新插件版本 ​

弃用插件 ​

发布插件

准备工作

补充更多信息

准入条件

添加相关信息

`koishi` 字段

发布插件

更新插件版本

弃用插件