🛠️ 环境安装

约 2423 字大约 8 分钟

2025-05-14

Node.js 铛铛铛！必需品

友情提示

Karin是一个基于Node.js开发的可爱机器人框架，在 MIT License 下开源~

版本要求

友情提示

🌟 推荐使用 Node.js 的 LTS 版本(v22+)，这样可以获得最稳定的体验哦！

小贴士：

最低支持 v18+，推荐使用 v22+
~~虽然理论上支持 v16+，但是为了获得最佳体验还是推荐使用更新版本啦~~
官方的LTS版本，所以跟着大家一起用 v22+ 准没错！
当然啦，如果你只是想尝鲜，用其他版本也不是不可以 😉

安装方式

友情提示

如果没有一定的基础，请勿随意使用nvm安装，否则可能会出现一些奇奇怪怪的问题哦

Windows 系统安装方法

Windows 系统

使用官方安装包(推荐)
- 访问 Node.js 官网下载安装包
- 如果无法访问，可以使用下方列表的安装包哦
- 下载 LTS 版本的 .msi 安装包
- 双击运行安装程序，全部下一步即可
使用 nvm-windows (适合需要管理多个 Node.js 版本的用户)
- 访问 nvm-windows 下载最新版本
- 下载 nvm-setup.exe 并安装
- 打开命令提示符(cmd)，运行:
```
nvm install latest  # 安装最新版
nvm install lts    # 安装 LTS 版本
nvm use xxx       # 使用指定版本
```

macOS 系统安装方法

macOS 系统

使用 Homebrew
```
brew install node
```

使用 nvm (推荐)

# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 2. 安装 Node.js
nvm install node    # 安装最新版
nvm install --lts  # 安装 LTS 版本
nvm use xxx       # 使用指定版本

Linux 系统安装方法

Linux 系统

使用包管理器

Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS/RHEL

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

使用 nvm (推荐)

# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 2. 安装 Node.js
nvm install node    # 安装最新版
nvm install --lts  # 安装 LTS 版本
nvm use xxx       # 使用指定版本

下载地址

友情提示

以下下载链接由 npmmirror 提供的国内镜像，如果无法访问请前往 Node.js 官网下载。

正在获取最新版本信息...

验证安装

友情提示

npm 是 Node.js 的自带的包管理器，安装Node.js时会自动安装

安装完成后，打开终端输入以下命令验证:

node -v  # 查看 Node.js 版本
npm -v   # 查看 npm 版本

如果能正确显示版本号，说明安装成功啦！

Git 可选项

友情提示

目前你无需安装Git 在已知的所有插件中并无任何Git相关的插件

Git 安装方法

Windows 安装

下载安装包:
- Git 官网
- 国内镜像源(推荐):
运行安装程序，全部使用默认选项即可

ps: 也就是一路Next，直到安装完成~

macOS 安装

brew install git

Linux 安装

Ubuntu/Debian

sudo apt-get update
sudo apt-get install git

CentOS/RHEL

sudo yum install git

验证安装

git --version  # 显示版本号即为安装成功

Redis 可选项

友情提示

Redis 目前使用 sqlite3 内置模拟了大部分常用的函数使用，在与真实 redis 上可能会有一定的差异，但这部分非常小。如果追求完美请按照下面的教程自行安装 redis-server。

Windows 系统安装方法

推荐使用：
- Redis-Windows
- 如果无法访问，请在 GitHub加速源下载 Redis-8.0.1-Windows-x64-msys2-with-Service.zip
下载后解压到任意目录

运行方式（三选一）：

方式一：直接运行脚本

# 直接运行项目中的 start.bat 脚本，一键启动
双击 start.bat

方式二：命令行启动

# CMD 启动
redis-server.exe redis.conf

# PowerShell 启动
./redis-server.exe redis.conf

方式三：安装为系统服务（开机自启）

# 安装服务（以管理员身份运行）
sc.exe create Redis binpath=C:\Software\Redis\RedisService.exe start= auto

# 启动服务
net start Redis

# 停止服务
net stop Redis

# 卸载服务
sc.exe delete Redis

注意：安装服务时请将 C:\Software\Redis\RedisService.exe 改为您实际存放的路径

macOS 系统安装方法

使用 Homebrew 安装：

brew install redis

# 启动服务
brew services start redis

Linux 系统安装方法

Ubuntu/Debian

sudo apt update
sudo apt install redis-server

# 启动服务
sudo systemctl start redis-server

CentOS/RHEL

sudo yum install redis

# 启动服务
sudo systemctl start redis

验证安装

redis-cli ping

如果返回 PONG，说明安装成功啦！

包管理器 pnpm 更快更好用！

什么是 pnpm？

pnpm 是一个快速、节省磁盘空间的包管理器。它具有以下特点：

比 npm/yarn 快 2-3 倍
节省磁盘空间，相同的依赖只会被存储一次
支持 monorepo，方便管理多个项目
更安全的依赖管理
你也不想你的依赖吃掉你的硬盘空间吧~

在 Karin 框架中，pnpm 的工作区(workspace)功能尤为重要：

所有的Git插件都是一个独立的工作区
可以统一管理所有插件的依赖
方便进行插件的开发和调试

安装 pnpm

友情提示

pnpm 在 10.x 版本引入了一个破坏性变更
~~目前暂时无法很好的对此进行兼容~~
请务必使用 pnpm v9 版本
如果已经安装了pnpm v10的小伙伴请不要跳过此步骤

新增版本: 1.8.0

目前已经对pnpm v10.x版本进行一定的适配
如果没有编程基础推荐使用9，无脑哦！！！
下方也列出了关于pnpm v10.x的指引
使用 pnpm v10.x 版本的用户请注意：

必须使用node-karin v1.8.0及以上版本
pnpm 必须使用 v10.8.0 及以上版本

配置镜像源

友情提示

国内的小伙伴们注意啦！如果访问官方源太慢，咱们换个源吧！

🚀 换源指南：

淘宝源

# 推荐使用这个，速度杠杠的！
npm config set registry https://registry.npmmirror.com

腾讯源

# 淘宝源不行？试试腾讯源！
npm config set registry https://mirrors.cloud.tencent.com/npm

官方源

# 想换回官方源也可以哦
npm config set registry https://registry.npmjs.org

pnpm 常用命令

小贴士

后面我们会经常用到 pnpm，建议先熟悉一下这些基本命令哦！
在开发插件时，工作区相关的命令会特别有用

# 工作区相关
pnpm -r install           # 安装所有工作区的依赖
pnpm --filter <pkg> add   # 为指定工作区安装依赖
pnpm -r update           # 更新所有工作区的依赖

# 基础命令
pnpm install      # 安装所有依赖
pnpm add <pkg>    # 安装某个包
pnpm add -D <pkg> # 安装开发依赖
pnpm up           # 更新所有依赖
pnpm update       # 更新所有依赖
pnpm rm <pkg>     # 删除某个包
pnpm remove <pkg> # 删除某个包
pnpm run <script> # 运行 package.json 中定义的脚本

关于`pnpm v10.x`版本

注

karin 非 1.8.0+ 的版本，请勿使用 pnpm v10.x

背景

警告

pnpm v10.x 版本引入了一个破坏性变更

官方原文如下:
Since v10, pnpm doesn't run the lifecycle scripts of dependencies unless they are listed in onlyBuiltDependencies.

从 v10 开始，pnpm 不会运行依赖项的生命周期脚本，除非它们在 onlyBuiltDependencies 中列出。
原文地址: 点击查看

我们使用sqlite3作为举例，sqlite3的安装需要编译二进制文件的
但是开发者为了方便用户的使用，会将构建产物预编译，并将这些构建产物托管到对应的代码平台上
这样用户在安装的时候就不需要自己编译了，直接下载对应的二进制文件即可
在pnpm v9.x版本中，执行pnpm install
sqlite3会执行一个install的脚本，来下载对应的二进制文件
在pnpm v10.x版本中，sqlite3的这个下载行为会被禁止，需要手动允许

如下所示:

解决方法

注

执行完成pnpm install后
如果出现了上图的这个提示，只需要跟着下面的步骤走就可以了哦~

输入 pnpm approve-builds
pnpm approve-builds
输入 a
a
按下回车也就是直接按下Enter键即可
enter
输入 y
y

到此为止，sqlite3的安装就完成了

注

当然，一个依赖只需要一次即可~
查看pnpm-workspace.yaml，会发现onlyBuiltDependencies中已经添加了对应的依赖
这样下次安装的时候就不会再询问了哦~

onlyBuiltDependencies:
  - '@karinjs/node-pty'
  - '@karinjs/sqlite3-cjs'
  - canvas
  - classic-level
  - sqlite3

写给开发者的话

注

如果你的插件依赖了包含生命周期脚本的依赖
可以将安装指令修改为如下所示
注意要求使用pnpm v10.8.0+版本哦~

pnpm add karin-plugin-xxx -w

修改为

# pnpm v9.x 版本
pnpm add karin-plugin-xxx -w

# pnpm v10.x 版本
pnpm --allow-build=sqlite3 add karin-plugin-xxx -w

如果是多个:

# pnpm v9.x 版本
pnpm add karin-plugin-xxx -w

# pnpm v10.x 版本
pnpm --allow-build=sqlite3 --allow-build=canvas add karin-plugin-xxx -w

贡献者

sj817

ikenxuan

疑难杂症

Utils

🛠️ 环境安装

Node.js 铛铛铛！必需品

版本要求

安装方式

Windows 系统

macOS 系统

Linux 系统

下载地址

验证安装

Git 可选项

Windows 安装

macOS 安装

Linux 安装

验证安装

Redis 可选项

验证安装

包管理器 pnpm 更快更好用！

什么是 pnpm？

安装 pnpm

配置镜像源

pnpm 常用命令

关于`pnpm v10.x`版本

背景

解决方法

写给开发者的话

贡献者