🐍 Conda (Miniforge) 环境管理手册

本手册用于管理 YOLOv11 的本地开发环境。使用 Conda 可以确保开发环境与系统环境隔离，避免库版本冲突。

1. 环境生命周期管理

🛠️ 创建环境 (仅需执行一次)

如果你在另一台电脑上复刻项目，或者需要重新搭建环境：

# 创建名为 yolo_env 的环境，并指定 Python 3.10
conda create -n yolo_env python=3.10 -y

# 激活环境以准备安装依赖
conda activate yolo_env

# 安装项目核心依赖
pip install fastapi "uvicorn[standard]" ultralytics onnxruntime pillow requests -i https://pypi.tuna.tsinghua.edu.cn/simple

➡️ 进入环境 (每次开发前)

开始工作或启动服务前，必须先激活环境：

1 2	conda activate yolo_env

注意：激活成功后，你的终端提示符左侧会出现 (yolo_env) 标志。

⬅️ 退出环境 (工作结束时)

当你需要切换到其他项目或回到系统默认环境时：

1 2	conda deactivate

❌ 删除环境

如果需要清理空间或彻底重装：

1 2	conda remove -n yolo_env --all -y

2. 常用维护命令表

动作	命令	说明
查看所有环境	`conda env list`	列出当前电脑上安装的所有虚拟环境
查看已装库	`pip list`	查看当前环境中安装了哪些 Python 包
导出配置	`conda env export > env.yml`	将环境依赖保存为文件，方便迁移
环境重命名	`conda create --name 新名 --clone 旧名`	变相实现环境重命名

3. Mac 提效进阶：设置终端快捷命令 (Alias)

为了避免每次都输入长长的 conda activate...，我们可以设置一个快捷键：

编辑配置文件（M1/M2 Mac 默认使用 zsh）：
1
2
nano ~/.zshrc

添加以下内容（请根据你的实际项目路径修改路径）：

1
2
3

# 一键进入 yolo 环境并跳转到项目目录
alias goyolo='conda activate yolo_env && cd /tire_project'

生效配置：
1
2
source ~/.zshrc

使用：以后只需在终端输入 goyolo 即可秒入开发状态。

4. 本地启动服务流程记录

为了确保 Token 认证生效，本地启动的最佳命令序列如下：

# 1. 进入环境
conda activate yolo_env

# 2. 设置 Token 并启动 (MacOS/Linux)
TIRE_API_KEY="TireAI_v1_8cf90224d55b4e7a8344e1c9878a2f3a61b8c0d9e" python -m uvicorn main:app --reload

5. 故障排查 (Troubleshooting)

问题：运行 python 时提示 ModuleNotFoundError: No module named 'ultralytics'。
解决：说明你没进入环境。请检查终端前缀是否有 (yolo_env)，若没有请运行 conda activate yolo_env。

问题：Mac 提示 conda: command not found。
解决：Miniforge 的路径没加到系统环境变量中。尝试运行 source ~/miniforge3/bin/activate 或检查安装路径。

conda_guide