从零安装 Python、配置包管理器与镜像源 — 确保你能顺利安装 NcatBot。

---

前提条件

• 一台 Windows / Linux / macOS 电脑
• 网络连接（中国大陆用户请关注下方镜像源配置）

1. 安装 Python

NcatBot 要求 Python ≥ 3.12。

Windows（推荐）

两种安装方式任选其一：

方式 A：官网安装包（推荐）

1. 访问 https://www.python.org/downloads/，找到并下载最新的 Python 3.12+ 安装包

如果你懒得找或者找不到

可以点击这里下载华为提供的镜像版本(下载链接)

2. 运行安装程序，务必勾选 "Add Python to PATH"（最重要的一步）
3. 选择 "Install Now" 即可

中国大陆下载慢？

如果 python.org 下载速度很慢，可以使用华为云镜像：https://mirrors.huaweicloud.com/python/，找到对应版本下载 .exe 安装包。或者点击上面的懒人链接直接下载。

方式 B：Microsoft Store

打开 Microsoft Store，搜索 "Python 3.12"，点击安装。优点是自动配置 PATH，缺点是版本更新可能稍慢。

Linux

大多数发行版自带 Python，但版本可能不够新：

# Ubuntu / Debian
sudo apt update
sudo apt install python3.12 python3.12-venv python3-pip

# 如果系统源没有 3.12，使用 deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv

macOS

NcatBot 不支持 macOS，请换一台电脑。

验证安装

python --version
# 输出示例：Python 3.12.x

Windows 用户注意

如果 python 命令无反应或打开 Microsoft Store，说明 PATH 没配置好。解决方法：

1. 重新运行 Python 安装程序，选择 "Modify"，确保勾选 "Add Python to PATH"
2. 或手动添加 Python 安装路径到系统环境变量 PATH

2. 包管理器

新手推荐：pip

pip 是 Python 自带的包管理器，安装 Python 后即可使用，无需额外配置：

# 安装 NcatBot
pip install ncatbot5

# 验证
python -c "import ncatbot; print('NcatBot 可用')"

进阶推荐：uv

uv 是新一代 Python 包管理器，速度比 pip 快 10-100 倍，自带虚拟环境管理：

# 安装 uv（Windows PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 安装 uv（Linux / macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh

使用 uv 管理项目：

# 初始化项目并安装 NcatBot
uv init my-bot
cd my-bot
uv add ncatbot5

# 运行
uv run python main.py

3. 中国大陆镜像源配置

pip 换源

# 临时使用（单次安装）
pip install ncatbot5 -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

# 永久配置（推荐）
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

常用镜像源：

镜像	地址
清华 TUNA	https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
阿里云	https://mirrors.aliyun.com/pypi/simple
中科大	https://pypi.mirrors.ustc.edu.cn/simple

uv 换源

# 设置环境变量（当前终端）
# PowerShell
$env:UV_INDEX_URL = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

# Linux / macOS
export UV_INDEX_URL="https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

永久生效

将上述环境变量添加到 PowerShell 配置文件（$PROFILE）或 ~/.bashrc 中，即可永久生效。

4. 虚拟环境

虚拟环境让每个项目拥有独立的依赖，避免不同项目之间的版本冲突。

使用 pip + venv（新手）

# 创建虚拟环境
python -m venv .venv

# 激活（Windows PowerShell）
.venv\Scripts\activate.ps1

# 激活（Linux / macOS）
source .venv/bin/activate

# 激活后安装依赖
pip install ncatbot5

使用 uv（进阶）

uv 会自动管理虚拟环境，无需手动创建：

uv add ncatbot5    # 自动创建 .venv 并安装
uv run ncatbot dev # 自动在虚拟环境中运行

常见问题

Python 版本不够

ERROR: ncatbot5 requires Python >=3.12

解决：卸载旧版本，安装 Python 3.12+。Windows 用户可以同时安装多个版本，使用 py -3.12 指定版本。

pip install 报 SSL 错误

SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

解决：这通常是公司/学校网络的 SSL 代理导致。临时绕过：

pip install ncatbot5 --trusted-host mirrors.tuna.tsinghua.edu.cn -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

PowerShell 禁止运行脚本

无法加载文件 .venv\Scripts\Activate.ps1，因为在此系统上禁止运行脚本

解决：以管理员身份运行 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

---

延伸阅读

• 安装完成后 → 安装与配置（NcatBot 配置与首次运行）
• 部署到服务器 → 部署指南

版权所有

版权归属：huan-yp

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