Koishi 安装教程

引言 ​

Koishi 是一个跨平台、可扩展、高性能的聊天机器人框架。

Koishi.chat

安装方式 ​

Koishi 官方提供了多种安装方式。包括但 Docker、模版项目、安装包等，支持 MacOS、Windows、linux、Android等系统。（Android 版本功能残缺，基本处于不可用状态，Android 系统上部署推荐使用 Termux）

系统为 Windows | 没有开发需求/对计算机一知半解 推荐使用 安装包(msi) 安装。

Windows 安装包安装教程请前往 Windows 安装包运行 安装。

系统为 Linux Desktop | 没有开发需求 推荐使用 安装包(Appimage) 安装。

Linux 安装包安装教程请参考 Windows 安装包运行 安装。

系统为 Linux Live Server | 没有开发需求/相对了解Docker 推荐使用 Docker 安装。

Docker 安装教程请前往Docker 运行

系统为 MacOS | 没有开发需求/对计算机一知半解 推荐使用 安装包(msi) 安装。

MacOS 安装包安装教程请参考 Windows 安装包运行 安装。

系统为 Android | 建议使用 Termux 使用一键脚本安装 Koishi Koimux_bot。不推荐使用 Koishi Android。

Android 安装教程请直接前往 Koishi Koimux_bot。

系统为 Linux/Windows/MacOS | 有开发需求/不熟悉 Docker 推荐使用 模版项目 。

Linux 模版项目教程请前往 Linux 模版项目运行

Windows 模版项目教程请前往 Windows 模版项目运行

由于笔者没有 MacOS 系统，请参考Linux 模版项目运行

Linux 模版项目运行 ​

本节将介绍我们最推荐的 Koishi 开发方案——创建模板项目。相比直接从零搭建，模板项目的优势在于：

• 创建完成即是拥有带完整控制台体验的项目，一键创建各种模板插件
• 支持直接加载 TypeScript，你可以尽情享受代码提示和类型检查带来的便利
• 支持插件热重载，你可以在不重启应用的情况下修改插件代码，并获得即时的反馈
• 支持二次开发，你可以将你自己的机器人与其他人的插件进行联合调试

当然，模板项目也可以直接用于生产。虽然在操作上可能不如启动器方便，但它提供了更多的自由度，并能在启动器所覆盖不到的场景下顺利运行。

安装Node.Js ​

本文推荐使用 NodeSource 软件源安装 Node.Js 。 NodeSource 是一个公司，聚焦于提供企业级的 Node 支持。它维护了一个 APT 软件源，其中包含了很多 Node.js 版本。

添加软件源 ​

输入以下命令添加软件源(如果你需要另外的 Node.js 版本，例如 23.x ，将 setup_22.x 修改为 setup_23.x ):

curl -sL https://deb.nodesource.com/setup_22.x | sudo -E bash -

正常添加源后，即可输入以下命令安装 Node.js

sudo apt install nodejs

安装 Yarn ​

我们推荐功能更强大的 yarn 作为包管理器。它的安装非常简单，只需打开命令行输入下面的命令：

# 安装 yarn
npm i -g yarn
# 查看 yarn 版本 
yarn -v

添加 Npm/Yarn 镜像源 ​

Nodejs 的包管理器 npm/yarn 的软件镜像源在中国大陆访问性不高。所以我们推荐更换为国内镜像源。

输入以下命令更换为淘宝镜像

npm config set registry https://registry.npmmirror.com

创建 Koishi ​

打开命令行，并进入你想要创建 Koishi 项目的目录。

输入下面的命令以创建 Koishi 项目：

npm init koishi@latest

启动 Koishi ​

如果你顺利完成了上述操作，你的应用此时应该已经是启动状态，并弹出了控制台界面。如果你想要关闭应用，可以在命令行中按下 Ctrl+C 组合键。当应用处于关闭状态时，你可以在运行下面的指令以再次启动：

npm start

Windows 模版项目运行 ​

本节将介绍我们最推荐的 Koishi 开发方案——创建模板项目。相比直接从零搭建，模板项目的优势在于：

• 创建完成即是拥有带完整控制台体验的项目，一键创建各种模板插件
• 支持直接加载 TypeScript，你可以尽情享受代码提示和类型检查带来的便利
• 支持插件热重载，你可以在不重启应用的情况下修改插件代码，并获得即时的反馈
• 支持二次开发，你可以将你自己的机器人与其他人的插件进行联合调试

当然，模板项目也可以直接用于生产。虽然在操作上可能不如启动器方便，但它提供了更多的自由度，并能在启动器所覆盖不到的场景下顺利运行。

安装Node.Js ​

我们首先要前往 Node.js 下载并安装 Node.js。或者直接点击直链下载 Nodejs v22.14.0

安装Node.js

安装 Yarn ​

我们推荐功能更强大的 yarn 作为包管理器。它的安装非常简单，只需打开命令行输入下面的命令：

# 安装 yarn
npm i -g yarn
# 查看 yarn 版本 
yarn -v

添加 Npm/Yarn 镜像源 ​

Nodejs 的包管理器 npm/yarn 的软件镜像源在中国大陆访问性不高。所以我们推荐更换为国内镜像源。

输入以下命令更换为淘宝镜像

npm config set registry https://registry.npmmirror.com

创建 Koishi ​

打开命令行，并进入你想要创建 Koishi 项目的目录。

输入下面的命令以创建 Koishi 项目：

npm init koishi@latest

启动 Koishi ​

如果你顺利完成了上述操作，你的应用此时应该已经是启动状态，并弹出了控制台界面。如果你想要关闭应用，可以在命令行中按下 Ctrl+C 组合键。当应用处于关闭状态时，你可以在运行下面的指令以再次启动：

npm start

Windows 安装包运行 ​

通过安装包安装 Koishi 是最推荐的安装方式，安装程序会自动处理大部分问题。一般情况下你都应该选择这种方式。

下载安装包 ​

我们首先要前往 Koishi 下载并安装 Node.js。或者直接点击直链下载 Koishi

安装 Koishi

安装运行 ​

等待安装完成之后，你可以在菜单栏中找到 Koishi 菜单项，点击它即可启动 Koishi。

启动 Koishi

Docker 运行 ​

使用Docker部署Koishi前，你需要确保你对 Docker 已经有了一定的了解。需要相对了解 Docker 之间的网络架构。

Docker 是一个开源的应用容器引擎，它允许开发者打包一个应用以及其依赖库到一个可移植的容器中，然后发布到任何流行的 Linux 或 Windows 机器上。容器是轻量级的、可移植的、自包含的运行环境，它们可以独立于宿主机运行。

安装Docker ​

我们在此提供两种办法运行 Koishi Docker。第一个是通过 1panel 应用商店一键运行 Koishi。你可以直接前往 1panel 获取到安装教程和技术支持。

现在我们介绍不依赖面板如果运行 Koishi Docker。

输入以下命令，使用一键脚本安装 Docker

bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

请根据自己服务器所在位置和网络选择镜像源。并安装 Docker

运行 Koishi ​

输入以下命令以运行 Koishi：

docker run -p 5140:5140 koishijs/koishi

许多插件依赖 koishi-plugin-puppeteer 来进行图片渲染，故默认镜像中包含 Chromium。如果你认为镜像过大，不需要预装 Chromium，我们也提供了轻量版本：

docker run -p 5140:5140 koishijs/koishi:latest-lite

启动后将会绑定 Koishi 控制台到 5140 端口。

如果你需要持久化，请使用 -v /some/place:/koishi 来映射 Koishi 的文件。

如果需要更正时区，请使用 -e TZ=Asia/Shanghai 来设置时区。