Miniconda 配置 AI 项目环境完整教程
从安装、环境创建、AI 依赖安装到 VS Code / Jupyter / GPU 验证，一篇跑通
标题
- 《Miniconda 配置 AI 项目环境完整教程：新手从安装到跑通 PyTorch》
- 《别再把 Python 环境装乱了：Miniconda 搭建 AI 项目环境保姆级教程》
- 《AI 项目环境怎么配？Miniconda、PyTorch、Jupyter、VS Code 一次讲清楚》
- 《Miniconda 新手入门：Windows、Mac、Linux 都能照着装》
- 《本地 AI 开发第一步：用 Miniconda 管好 Python 环境》
文章导读
做 AI 项目最容易踩坑的地方，不是模型，也不是代码，而是 Python 环境。很多新手会把所有依赖都装进系统 Python 或 base 环境里，结果几天后就遇到版本冲突、包找不到、GPU 不可用、VS Code 解释器选错等问题。
Miniconda 的价值在于“轻量、可控、可复现”：它不会像 Anaconda Distribution 一样默认安装大量数据科学包，而是只提供 conda、Python 和少量基础组件，让你根据项目需要逐步安装依赖。
这篇教程面向 AI 初学者、数据分析师、独立开发者和服务器部署用户，带你从零完成 Miniconda 安装、AI 环境创建、PyTorch / Transformers / Jupyter 配置、VS Code 接入、GPU 验证、环境导出迁移和常见问题排查。
一、Miniconda 是什么？为什么适合 AI 项目？
Miniconda 是 Anaconda 提供的轻量版 conda 安装器，默认只包含 conda、Python 和少量必要包。相比 Anaconda Distribution，它更适合“按需安装”的 AI 项目环境管理。
| 工具 | 适合人群 | 优点 | 注意事项 |
| Miniconda | AI 开发者、服务器用户、希望轻量安装的人 | 体积小、安装快、可按项目创建环境 | 需要自己安装 Jupyter、PyTorch 等依赖 |
| Anaconda Distribution | 数据科学新手、课程教学、离线实验环境 | 默认包含大量常用科学计算包和 Navigator | 体积较大，项目越多越容易混乱 |
| Miniforge / Mambaforge | 偏向 conda-forge 生态、开源渠道优先用户 | 默认使用 conda-forge，依赖求解体验好 | 企业环境要确认来源与合规要求 |
| 系统 Python + venv | 轻量脚本、Web 项目、纯 Python 项目 | 简单、官方、无额外发行版依赖 | 处理 CUDA、科学计算二进制包时不如 conda 稳定 |
提示：AI 项目建议“一项目一环境”。不要把所有包都装进 base，也不要把多个模型项目共用同一个环境。
二、安装前准备：先确认电脑和项目类型
正式安装前，先判断自己属于哪类使用场景。Miniconda 可以同时支持 Windows、macOS 和 Linux，但不同系统的终端、路径、GPU 驱动和 IDE 接入方式略有差异。
| 检查项 | 推荐做法 |
| 操作系统 | Windows 10/11、macOS、Ubuntu/Debian/Rocky 等均可；服务器建议优先使用 Linux。 |
| Python 版本 | AI 项目建议优先使用 Python 3.10 或 3.11，兼容性通常更稳。 |
| 磁盘空间 | 基础 Miniconda 很小，但模型、CUDA、PyTorch、缓存会占用大量空间，建议预留 20GB 以上。 |
| GPU | NVIDIA GPU 用户先安装显卡驱动并确认 nvidia-smi 可用；Apple Silicon 走 CPU/MPS 或框架特定方案。 |
| 网络 | 国内网络环境下可能需要镜像源或代理，但应优先保留官方渠道作为基准。 |
| 权限 | 个人电脑建议安装到用户目录；服务器不要随意使用 root 环境管理项目依赖。 |
三、Windows 安装 Miniconda
Windows 用户可以使用图形安装器，也可以使用命令行安装器。新手建议先用官方图形安装器，安装完成后通过“Anaconda Prompt”或“Miniconda Prompt”验证。
- 进入 Miniconda 官方下载页面，选择 Windows 64-bit installer。
- 双击安装器，安装位置建议选择用户目录，例如 C:\Users\你的用户名\miniconda3。
- 安装选项中，不建议随意勾选“Add to PATH”，新手使用 Anaconda Prompt 更稳。
- 安装完成后，在开始菜单打开 Anaconda Prompt 或 Miniconda Prompt。
- 输入 conda list，如果能看到包列表，说明安装成功。
conda –version
conda list
where conda
提示：Windows PowerShell 中如果 conda activate 不生效，可运行 conda init powershell 后关闭并重新打开 PowerShell。
conda init powershell
# 关闭并重新打开 PowerShell 后再试
conda activate base
四、macOS 安装 Miniconda
macOS 用户要区分 Apple Silicon 与 Intel 芯片。Apple Silicon 包括 M1、M2、M3、M4 系列；Intel Mac 则选择 x86_64 版本。图形安装器适合新手，命令行安装器适合开发者和服务器式管理。
| Mac 类型 | 安装包选择 | 建议 |
| Apple Silicon Mac | macOS Apple silicon / arm64 | 优先安装原生 arm64 版本，避免 Rosetta 环境混乱。 |
| Intel Mac | macOS Intel / x86_64 | 选择 Intel 版本安装器。 |
| 多用户或开发者 | 命令行 installer | 可安装到用户目录，更利于环境管理和卸载。 |
# 安装完成后验证
conda –version
conda list
# 初始化 zsh（macOS 默认 shell 通常是 zsh）
conda init zsh
# 关闭并重新打开终端
五、Linux 服务器安装 Miniconda
Linux 服务器通常没有图形界面，推荐使用命令行安装器。安装前确认系统架构，常见云服务器大多是 x86_64；ARM 服务器需要选择 aarch64 安装包。
# 示例：下载 Linux x86_64 安装脚本（请以官网最新文件名为准）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
# 可选：校验安装包哈希
sha256sum Miniconda3-latest-Linux-x86_64.sh
# 安装
bash Miniconda3-latest-Linux-x86_64.sh
# 初始化 bash
conda init bash
# 重新打开终端或重新加载配置
source ~/.bashrc
# 验证
conda –version
conda list
提示：服务器上建议关闭 base 自动激活，避免登录后误把依赖装进 base。
conda config –set auto_activate_base false
六、Miniconda 基础配置：先把环境管理习惯立住
装好 Miniconda 后，不要急着安装一堆包。先完成三个基础配置：关闭 base 自动激活、确认频道策略、学会清理缓存。
# 1. 关闭 base 自动激活
conda config –set auto_activate_base false
# 2. 查看当前配置
conda config –show
# 3. 查看频道
conda config –show channels
# 4. 设置严格频道优先级（减少跨频道冲突）
conda config –set channel_priority strict
# 5. 清理缓存
conda clean -a
频道配置不要频繁混用。比如一个环境长期使用 defaults，就尽量不要突然大量混入 conda-forge；如果决定用 conda-forge，最好新建环境并设置 strict channel priority。
七、创建第一个 AI 项目环境
下面以创建一个名为 ai-demo 的 AI 项目环境为例。Python 版本建议选择 3.10 或 3.11，因为很多 AI 库对这两个版本支持较成熟。
# 创建环境
conda create -n ai-demo python=3.11 -y
# 激活环境
conda activate ai-demo
# 确认当前 Python 来自该环境
python –version
python -c “import sys; print(sys.executable)”
# 升级 pip
python -m pip install –upgrade pip
提示：每次安装包前，先看命令行前缀是否出现 (ai-demo)。如果没有激活环境，就不要继续装包。
八、安装 AI 项目常用基础包
AI 项目通常会用到科学计算、可视化、Notebook、模型调用、Web Demo 等依赖。建议分层安装，先装基础包，再装大模型和 GPU 相关包。
# 基础科学计算与可视化
conda install numpy pandas matplotlib scikit-learn ipykernel -y
# JupyterLab
conda install jupyterlab -y
# 常见 AI / LLM 开发包
pip install transformers accelerate datasets sentencepiece tokenizers
pip install openai langchain gradio fastapi uvicorn python-dotenv
| 包/工具 | 作用 | 安装建议 |
| numpy / pandas | 数值计算、数据处理 | 优先用 conda 安装，依赖更稳。 |
| matplotlib / scikit-learn | 绘图、传统机器学习 | conda 或 pip 均可，建议同一环境里少混乱。 |
| JupyterLab / ipykernel | Notebook 与交互实验 | 每个环境都安装 ipykernel 并注册内核。 |
| PyTorch | 深度学习训练和推理 | 严格按官网安装选择器复制命令。 |
| transformers / accelerate | Hugging Face 模型生态 | 一般使用 pip 安装更新更快。 |
| gradio / fastapi | 快速做 Demo 或 API 服务 | 适合本地模型测试和部署验证。 |
九、安装 PyTorch：CPU 和 GPU 分开处理
PyTorch 是很多 AI 项目的核心依赖。安装时不要凭记忆写命令，建议打开 PyTorch 官方 Get Started 页面，按系统、包管理器、语言和计算平台选择命令。
1. CPU 版安装
没有 NVIDIA 显卡、只是跑轻量模型或做基础学习时，可以先安装 CPU 版。CPU 版更简单，也更容易排查。
# 示例：CPU 版请以 PyTorch 官网生成命令为准
pip install torch torchvision torchaudio
# 验证
python -c “import torch; print(‘torch:’, torch.__version__); print(‘cuda available:’, torch.cuda.is_available())”
2. GPU 版安装
NVIDIA GPU 用户先确认驱动正常，再按 PyTorch 官网选择对应 CUDA 计算平台。很多情况下，PyTorch pip 包会自带所需 CUDA runtime，普通训练和推理不一定需要单独安装完整 CUDA Toolkit。
# 第一步：确认显卡驱动可用
nvidia-smi
# 第二步：复制 PyTorch 官网命令安装 GPU 版
# 示例仅作格式参考，请以官网 selector 当前结果为准
pip install torch torchvision torchaudio –index-url https://download.pytorch.org/whl/cu128
# 第三步：验证 GPU
python -c “import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())”
提示：不要只看本机安装的 CUDA Toolkit 版本。PyTorch 是否能用 GPU，关键看 NVIDIA 驱动、PyTorch 包版本和 CUDA runtime 是否匹配。
十、把 conda 环境接入 VS Code
VS Code 不会自动“使用你想要的环境”，它只会根据当前工作区选择一个 Python 解释器。你需要明确指定 ai-demo 环境。
- 安装 VS Code 的 Python 扩展。
- 打开项目文件夹，并创建或打开一个 .py 文件。
- 按 Ctrl+Shift+P（Mac 为 Cmd+Shift+P），搜索 Python: Select Interpreter。
- 选择带有 ai-demo 或 conda 字样的解释器。
- 打开终端，确认 python -c “import sys; print(sys.executable)” 指向 ai-demo。
# 在 VS Code 终端中验证
python -c “import sys; print(sys.executable)”
python -c “import torch; print(torch.__version__)”
提示：如果 VS Code 找不到环境，先打开一个 .py 文件，再刷新解释器列表；仍找不到时，手动选择 miniconda3/envs/ai-demo/bin/python 或 Windows 下的 envs\ai-demo\python.exe。
十一、把 conda 环境注册到 JupyterLab
很多人遇到“终端能 import，但 Notebook 里 import 报错”，本质是 Notebook 内核和终端环境不是同一个。解决办法是给当前 conda 环境注册 ipykernel。
conda activate ai-demo
conda install ipykernel -y
python -m ipykernel install –user –name ai-demo –display-name “Python (ai-demo)”
# 启动 JupyterLab
jupyter lab
进入 JupyterLab 后，新建 Notebook 时选择 “Python (ai-demo)” 内核。以后每个项目都可以用类似方式注册自己的内核。
十二、环境导出、迁移与复现
AI 项目要长期维护，不能只靠“我电脑上能跑”。最少要保留一个环境文件，方便以后换电脑、部署服务器或协作开发。
# 导出完整环境（信息多，适合本机备份）
conda env export > environment.yml
# 导出手动安装历史（更轻，适合跨平台参考）
conda env export –from-history > environment-lite.yml
# 从环境文件创建环境
conda env create -f environment.yml
# 更新已有环境
conda env update -f environment.yml –prune
# 只导出 pip 包
pip freeze > requirements.txt
| 文件 | 适合用途 | 注意事项 |
| environment.yml | 完整复现 conda 环境 | 可能包含平台相关包，跨系统迁移时需检查。 |
| environment-lite.yml | 记录手动指定依赖 | 更清爽，但可能需要重新解析依赖。 |
| requirements.txt | pip 项目依赖 | 适合纯 pip 项目或配合 conda 环境使用。 |
| pyproject.toml | 现代 Python 项目配置 | 适合包开发、CLI 工具、规范化项目。 |
十三、常用 conda 命令速查
| 目标 | 命令 |
| 查看 conda 版本 | conda –version |
| 查看环境列表 | conda env list 或 conda info –envs |
| 创建环境 | conda create -n ai-demo python=3.11 -y |
| 激活环境 | conda activate ai-demo |
| 退出环境 | conda deactivate |
| 安装包 | conda install 包名 -y 或 pip install 包名 |
| 查看已安装包 | conda list 或 pip list |
| 删除环境 | conda remove -n ai-demo –all |
| 克隆环境 | conda create -n ai-copy –clone ai-demo |
| 清理缓存 | conda clean -a |
| 查看配置 | conda config –show |
| 设置严格频道优先级 | conda config –set channel_priority strict |
十四、AI 项目环境模板：直接复制使用
下面给出三个常见模板：轻量 LLM 调用、PyTorch GPU、Notebook 数据分析。读者可以根据自己的项目复制修改。
模板 1：轻量 LLM API / 自动化脚本
conda create -n llm-tools python=3.11 -y
conda activate llm-tools
python -m pip install –upgrade pip
pip install openai python-dotenv requests rich typer pydantic
模板 2：PyTorch GPU 项目
conda create -n torch-ai python=3.11 -y
conda activate torch-ai
python -m pip install –upgrade pip
# PyTorch 命令请从官网选择器复制
pip install torch torchvision torchaudio –index-url https://download.pytorch.org/whl/cu128
pip install transformers accelerate datasets sentencepiece tqdm
模板 3：Notebook 数据分析环境
conda create -n data-lab python=3.11 -y
conda activate data-lab
conda install numpy pandas matplotlib scikit-learn jupyterlab ipykernel -y
python -m ipykernel install –user –name data-lab –display-name “Python (data-lab)”
jupyter lab
十五、常见问题排查
问题 1：conda 命令找不到怎么办？
先关闭并重新打开终端。如果仍找不到，Windows 用 Anaconda Prompt 验证；macOS/Linux 检查安装目录是否存在，并运行对应 shell 的 conda init。
# macOS / Linux
~/miniconda3/bin/conda –version
~/miniconda3/bin/conda init bash
~/miniconda3/bin/conda init zsh
问题 2：conda activate 报错怎么办？
这通常是 shell 没有初始化。执行 conda init 后必须重新打开终端，不能只在当前窗口继续试。
conda init bash # Linux 常见
conda init zsh # macOS 常见
conda init powershell # Windows PowerShell
问题 3：Solving environment 卡很久怎么办？
- 尽量新建干净环境，而不是在旧环境里反复修补。
- 不要在同一个环境中频繁混用 defaults、conda-forge、pytorch、nvidia 等多个频道。
- 设置 strict channel priority，减少跨频道依赖冲突。
- 必要时考虑 mamba，但新手先掌握 conda 基础命令。
问题 4：pip 安装了包，但 Python 找不到怎么办？
最常见原因是 pip 和 python 不属于同一个环境。建议使用 python -m pip install，而不是直接 pip install。
python -c “import sys; print(sys.executable)”
python -m pip –version
python -m pip install 包名
问题 5：torch.cuda.is_available() 是 False 怎么办？
- 先运行 nvidia-smi，确认驱动能识别显卡。
- 确认你安装的是 GPU 版 PyTorch，而不是 CPU 版。
- 按 PyTorch 官网选择器复制命令，不要自己拼 CUDA 版本。
- 云服务器或 Docker 环境还要确认 GPU 是否被容器识别。
十六、最佳实践：让环境长期不崩
- 永远不要把项目依赖装进 base 环境。
- 每个项目建立独立 conda env，环境名和项目名保持一致。
- 项目根目录保留 environment.yml 或 requirements.txt。
- 安装大型依赖前先保存当前环境文件，方便回滚。
- 优先复制官方安装命令，尤其是 PyTorch、CUDA、深度学习框架。
- VS Code、Jupyter、终端三者必须指向同一个解释器。
- 服务器部署时不要随意用 root 用户管理所有项目。
FAQ：Miniconda 配置 AI 项目环境常见问题
Q1：Miniconda 和 Anaconda 应该选哪个？
如果你只是想搭建 AI 项目环境，推荐 Miniconda。它更轻量、可控，适合按项目安装依赖。Anaconda 更适合课程教学和一次性安装大量数据科学包。
Q2：Miniconda 能不能和系统 Python 共存？
可以。Miniconda 会安装在独立目录中，只要不乱改 PATH，通常不会影响系统 Python。
Q3：为什么不建议在 base 环境里装包？
base 是 conda 自身运行基础环境，装太多项目依赖后容易出现版本冲突。一旦 base 损坏，所有环境管理都会受影响。
Q4：conda 和 pip 能混用吗？
可以，但要谨慎。建议先用 conda 安装底层科学计算包，再用 pip 安装更新更快的 AI 生态包。混用后一定要记录依赖文件。
Q5：AI 项目应该用 Python 3.12/3.13 吗？
新项目可以尝试，但很多 AI 库对 3.10/3.11 的兼容更稳。新手优先选择 Python 3.11。
Q6：安装 PyTorch 是否必须先装 CUDA Toolkit？
普通用户通常先按 PyTorch 官网命令安装即可。是否需要 CUDA Toolkit 取决于是否要编译自定义 CUDA 扩展。
Q7：Jupyter Notebook 里找不到刚创建的环境怎么办？
在该环境里安装 ipykernel，并运行 python -m ipykernel install –user –name 环境名 –display-name “Python (环境名)”。
Q8：VS Code 明明装了包却 import 报错怎么办？
大概率是 VS Code 解释器选错了。使用 Python: Select Interpreter 选择对应 conda 环境。
Q9：环境太大怎么清理？
可以运行 conda clean -a 清理缓存；不用的环境用 conda remove -n 环境名 –all 删除。
Q10：团队协作怎么保证环境一致？
在项目仓库中提交 environment.yml、requirements.txt 或 pyproject.toml，并在 README 中写明 Python 版本和安装命令。
官方参考资料
- Miniconda 官方安装说明：https://www.anaconda.com/docs/getting-started/miniconda/install/overview
- conda 管理环境官方文档：https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/manage-environments.html
- conda init 官方说明：https://docs.conda.io/projects/conda/en/stable/commands/init.html
- conda 频道管理官方文档：https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-channels.html
- PyTorch 官方安装选择器：https://pytorch.org/get-started/locally/
- VS Code Python 环境文档：https://code.visualstudio.com/docs/python/environments
- Jupyter 官方安装说明：https://jupyter.org/install
