快速入门

约 1255 字大约 4 分钟

2026-03-19

5 分钟跑通你的第一个 NcatBot 插件。

环境准备

依赖	要求	说明
Python	≥ 3.12	`python --version` 验证
uv	最新版	推荐的包管理器，安装指南
NapCat	最新版	QQ 协议端，NcatBot 会自动下载安装

提示

如果你还没有 uv，也可以直接用 pip。NapCat 在首次运行时会自动下载配置。

asyncio 速查

NcatBot 是一个 异步框架，插件中的事件处理器都是异步函数。如果你不熟悉 Python 异步编程，这里是 5 个核心概念：

import asyncio

# 1. async def 定义协程函数
async def greet(name: str) -> str:
    return f"Hello, {name}"

# 2. await 等待协程完成并获取结果
async def main():
    result = await greet("World")
    print(result)  # Hello, World

# 3. asyncio.create_task() 并发执行多个协程
async def main():
    task1 = asyncio.create_task(greet("A"))
    task2 = asyncio.create_task(greet("B"))
    results = await asyncio.gather(task1, task2)

# 4. async for 异步迭代
async def consume(stream):
    async for item in stream:
        print(item)

# 5. async with 异步上下文管理器
async def use_resource():
    async with some_resource() as res:
        await res.do_something()

在 NcatBot 中，你只需记住：

事件处理器用 async def 定义
调用 API 时用 await（如 await event.reply("hello")）
框架负责运行事件循环，你不需要手动调用 asyncio.run()

安装 NcatBot

# 推荐：使用 uv
uv add ncatbot5

# 或者：使用 pip
pip install ncatbot5

验证安装：

python -c "import ncatbot; print(ncatbot.__version__)"

准备配置文件

在项目根目录创建 config.yaml：

# 必填：你的 QQ 号
bot_uin: '123456789'

# 可选：超级管理员 QQ 号
root: '123456'

# 适配器配置（NapCat 连接）
adapters:
  - type: napcat
    platform: qq
    enabled: true
    config:
      ws_uri: ws://localhost:3001
      ws_token: napcat_ws

# 插件配置
plugin:
  plugins_dir: plugins    # 插件目录
  load_plugin: true       # 是否加载插件

将 bot_uin 替换为你的实际 QQ 号。其他配置项保持默认即可，完整配置说明参见配置管理指南。

启动 Bot

创建入口文件 main.py：

from ncatbot.app import BotClient

bot = BotClient()

if __name__ == "__main__":
    bot.run()

bot.run() 会依次完成：

加载 config.yaml 配置
启动 NapCat（首次运行自动下载安装）
建立 WebSocket 连接
扫描 plugins/ 目录，加载所有插件
开始监听事件

编写第一个插件

1. 创建插件目录

plugins/
└── hello_world/
    ├── manifest.toml
    └── main.py

2. 编写 manifest.toml

每个插件必须有一个 manifest.toml 清单文件，声明插件的基本信息：

name = "hello_world"
version = "1.0.0"
main = "main.py"
entry_class = "HelloWorldPlugin"
author = "NcatBot"
description = "最小可运行插件 — 演示基础生命周期与消息回复"

字段	必填	说明
`name`	✅	插件唯一标识
`version`	✅	语义化版本号
`main`	✅	入口文件名
`entry_class`	❌	插件类名（省略则自动发现）
`author`	❌	作者
`description`	❌	插件描述

完整字段说明参见插件结构 — manifest.toml 详解。

3. 编写 main.py

from ncatbot.core import registrar
from ncatbot.event.qq import GroupMessageEvent, PrivateMessageEvent
from ncatbot.plugin import NcatBotPlugin
from ncatbot.utils import get_log

LOG = get_log("HelloWorld")


class HelloWorldPlugin(NcatBotPlugin):
    name = "hello_world"
    version = "1.0.0"
    author = "NcatBot"
    description = "最小可运行插件 — 回复 hello"

    async def on_load(self):
        LOG.info("HelloWorld 插件已加载！")

    async def on_close(self):
        LOG.info("HelloWorld 插件已卸载。")

    @registrar.on_group_command("hello", ignore_case=True)
    async def on_hello(self, event: GroupMessageEvent):
        """收到群消息 'hello' 时回复"""
        await self.api.qq.post_group_msg(event.group_id, text="Hello, World! 👋")

    @registrar.on_group_command("hi", ignore_case=True)
    async def on_hi(self, event: GroupMessageEvent):
        """用 event.reply() 快速回复（自动引用 + @发送者 + 文字）"""
        await event.reply(text="你好呀！这是通过 event.reply() 发送的快速回复 🎉")

    @registrar.on_private_command("hello", ignore_case=True)
    async def on_private_hello(self, event: PrivateMessageEvent):
        """收到私聊消息 'hello' 时回复"""
        await event.reply(text="你好！这是来自 HelloWorld 插件的私聊回复 👋")

完整源码：examples/qq/01_hello_world/

关键概念解读

元素	说明
`NcatBotPlugin`	插件基类，内置了配置、数据、权限、定时任务等 Mixin 能力
`on_load()`	插件加载时调用——在这里注册事件处理器、初始化数据
`on_close()`	插件卸载时调用——在这里做清理工作
`@registrar.on_group_command("hello")`	注册群命令处理器：当群消息内容为 "hello" 时触发
`@registrar.on_private_command("hello")`	注册私聊命令处理器
`event: GroupMessageEvent`	事件实体，包含消息内容、发送者、群号等信息
`event.reply(text="...")`	便捷回复：自动引用原消息 + @发送者
`self.api.qq.post_group_msg(group_id, text="...")`	直接调用 API 发送群消息
`get_log("name")`	获取日志实例

运行与测试

# 启动 Bot
python main.py

启动后：

在群里发送 hello → 收到 "Hello, World! 👋"
在群里发送 hi → 收到引用回复 + @你 + "你好呀！..."
私聊 Bot 发送 hello → 收到私聊回复

如果看到日志 HelloWorld 插件已加载！，说明插件加载成功。

下一步

恭喜！你已经成功运行了第一个 NcatBot 插件。接下来推荐阅读：

插件结构 — 深入了解 manifest.toml 字段、基类选择、目录布局
生命周期 — 理解插件的加载/卸载流程
事件处理 — 掌握三种事件消费模式
消息类型详解 — 学习构造图文、@、转发等复杂消息

版权所有

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

通用

QQ

Bilibili

GitHub

通用

QQ