Windows 安装

约 1586 字大约 5 分钟

2025-02-07

运行你的第一个 Bot !

注意

如果使用服务器部署，强烈不建议使用 Windows Server，建议使用基于 Ubuntu 操作系统的服务器。

任务列表

我们给出一个简单的任务清单, 你可以按照下面的步骤来安装 NcatBot.

在你的电脑上安装 Python >= 3.10 (推荐 3.12).
通过 pip 安装 NcatBot.
检查环境是否正常.
扫码登录 NcatBot.

1. 安装 Python

如果你还不会安装 Python, 请先在菜鸟教程认真学习 Python 相关的知识后再使用本项目.

这里给出一个正确的 Python 安装包. 下载后双击安装.

安装时请一定注意, 保证 Add Python 3.12 to PATH 处于勾选状态, 其余选项保持默认.

2. 安装 NcatBot

项目已经发布到 PYPI, 可以使用 pip 直接下载本项目.

按下 Win+R, 在左下角打开运行, 输入 powershell 并回车, 打开终端.

复制下面的代码, 粘贴到终端中, 按回车执行.

pip(稳定版, 推荐)

pip install ncatbot -U -i https://mirrors.aliyun.com/pypi/simple

Gitee(过时, 不推荐)

pip install git+https://gitee.com/li-yihao0328/nc_bot.git

GitHub(开发预览版, 不推荐)

pip install git+https://github.com/liyihao1110/ncatbot.git

如果你下载过 github 上的 .zip 压缩文件并解压出来过, 请删掉它们.

如果出现红色的错误信息, 例如:

pip : 无法将“pip”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径
正确，然后再试一次。

说明没能成功安装 Python, 一般是因为第一个页面没能勾选 Add Python 3.xx to PATH, 或者是因为第二个页面取消了 pip 的勾选.

如果中途没有出现红色的错误信息, 并且最后出现:

Successfully installed Markdown-3.7 Pillow-11.1.0 Pygments-2.19.1 anyio-4.9.0 appdirs-1.4.4 certifi-2025.1.31 charset-normalizer-3.4.1 colorama-0.4.6 gitdb-4.0.12 gitpython-3.1.44 h11-0.14.0 httpcore-1.0.7 httpx-0.28.1 idna-3.10 importlib-metadata-8.6.1 ncatbot-3.5.9 packaging-24.0 psutil-6.1.1 pyee-11.1.1 pyppeteer-2.0.0 pyyaml-6.0.2 qrcode-8.0 qrcode-terminal-0.8 requests-2.32.3 schedule-1.2.2 smmap-5.0.2 sniffio-1.3.1 tqdm-4.67.1 typing-extensions-4.12.2 urllib3-1.26.20 websockets-10.4 zipp-3.21.0

则说明安装成功.

3. 检查运行环境

检查 NcatBot 是否安装成功

在终端中, 输入 python 并回车, 打开 Python 交互模式.

复制以下代码, 粘贴进去, 回车执行.

python

import ncatbot
print(ncatbot.__version__)

如果输出了版本号, 例如 3.8.6（2025.5.21）则说明安装成功。

检查 QQ 版本

NcatBot 需要 QQ 版本至少达到 9.9.19 才能正常运行, 如果你不知道你的 QQ 是哪个版本, 请前往官网或者点击这里的官方下载链接下载最新版 QQ 的安装包. 双击安装包更新即可.

准备 QQ 号

为了测试, 需要两个 QQ 号：

一个 QQ 号称为 Bot, Bot 一般是小号, 它由 NcatBot 控制.
另一个 QQ 号称为 root, root 一般是大号, 由你自己控制, 拥有管理 Bot 的权限.

确保没有重复登录

Bot 必须处于电脑不在线状态, 检查自己的电脑, 如果电脑上登录了 Bot, 请退出登录.

4. NcatBot 启动

建立一个新的工作目录(文件夹), 比如建一个 ncatbot 文件夹, 进行如下操作:

双击进入 ncatbot 文件夹.
执行主函数:
方法一
1. 在文件夹中打开终端(右键这个文件夹的空白区域, 选择 "在终端中打开"), 输入 python 并回车打开 Python 交互终端.
2. 复制执行下面的代码(记得把代码中的 bt_uin 改成 Bot QQ 号, 把 root 改成 root QQ 号)并回车执行.
方法二
1. 在文件夹中创建一个新文件, 名为 main.py, 注意文件的后缀名是 .py.
2. 用记事本等文本编辑器打开 main.py 文件, 复制下面的代码, 粘贴进去, 并记得把代码中的 bt_uin 改成 Bot QQ 号, 把 root 改成 root QQ 号
3. Ctrl+S 保存.
4. 在文件夹中打开终端(右键这个文件夹的空白区域, 选择 "在终端中打开"), 输入 python main.py 并回车执行.
如果是第一次执行, 可能会弹出一个窗口询问是否允许修改, 选择是. 等待一段时间后, 会显示二维码. 扫码时, 需要在手机上先登录 Bot QQ 号, 用手机扫码登录.
用 root QQ 号向你的 Bot QQ 号私聊发送一句 测试, 收到 NcatBot 测试成功喵~ 的消息, 说明 NcatBot 已经成功运行起来了!
请注意, 请不要关闭打开的两个终端窗口(黑框框), 否则 NcatBot 将无法正常运行.

python

# ========= 导入必要模块 ==========
from ncatbot.core import BotClient, GroupMessage, PrivateMessage
from ncatbot.utils import get_log

# ========== 创建 BotClient ==========
bot = BotClient()
_log = get_log()

# ========= 注册回调函数 ==========
@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg)
    if msg.raw_message == "测试":
        await msg.reply(text="NcatBot 测试成功喵~")

@bot.private_event()
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == "测试":
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 测试成功喵~")

# ========== 启动 BotClient==========
if __name__ == "__main__":
    bot.run(bt_uin="123456") # 这里写 Bot 的 QQ 号