1. 课程导入与学习路径规划
在正式动手安装任何软件之前，先想清楚一件事：我们为什么要专门花一整章来讨论“环境配置与版本管理”？Qiskit 是一个快速演进的量子计算 SDK，从 0.x 到 1.x 的版本跨度中，大量 API 被重命名、迁移甚至移除。很多初学者遇到的第一个报错并不是量子电路写错了，而是 ImportError、ModuleNotFoundError 或某个函数“突然不存在了”。这类问题的根源几乎都指向同一个地方——环境与版本。
本课程的核心目标可以概括为三层：装得上、跑得通、管得住。“装得上”指能在本机或远程正确安装 Python 与 Qiskit 包家族；“跑得通”指能写出并执行第一个量子电路，看到确定的测量统计结果；“管得住”指能用虚拟环境和依赖锁定，让同一份代码在几个月后、在另一台机器上仍然可复现。三层目标层层递进，缺一不可。
关键工具链的分工
Qiskit 的开发环境不是单一软件，而是一条工具链。理解每个环节的职责，比记住安装命令更重要。
- Python：运行时与语言基础。Qiskit 1.x 要求 Python 3.9 及以上，建议直接使用 3.10 或 3.11，兼顾新特性与第三方库兼容性。
- pip：Python 官方包安装器，从 PyPI 拉取 wheel 包，是安装 Qiskit 最直接的方式。
- conda：跨语言的环境与包管理器，优势在于能同时管理 Python 版本和非 Python 依赖（如某些编译库），适合需要多版本并存的场景。
- 虚拟环境：
venv或 conda env，为每个项目隔离一套独立的包目录，避免项目 A 升级 Qiskit 后项目 B 崩溃。 - Qiskit 包家族：Qiskit 1.x 起采用“元包 + 分件”结构，
qiskit是聚合入口，底层拆分为qiskit-terra（电路与编译核心）、qiskit-aer（高性能模拟器）、qiskit-ibm-runtime（访问 IBM 真实设备）等。
下图展示了这条工具链的层次关系与数据流向：从操作系统出发，经 Python 运行时，到虚拟环境隔离层，再到 Qiskit 包家族，最终抵达两类执行后端。
学习路线图
本课程 30 章按“认知—搭建—验证—管理—进阶”的顺序推进，可以划分为四个阶段。第一阶段建立概念地图，弄清 Python、pip、conda、虚拟环境与 Qiskit 包家族各自的位置；第二阶段动手搭建，从安装 Python 到创建虚拟环境、安装 Qiskit、验证导入；第三阶段进入版本管理，学习依赖锁定、环境导出、多版本共存与升级回滚；第四阶段面向工程实践，处理离线安装、CI 环境、团队协作与常见故障排查。
建议的学习节奏是：每完成一个安装或配置动作，立刻用一条最小命令验证结果，而不是等到最后统一测试。例如创建虚拟环境后，先执行 python -c "import sys; print(sys.executable)" 确认解释器路径指向虚拟环境内部，再安装 Qiskit。这种“小步验证”的习惯能大幅缩短排错时间。
常见误区概览
在正式进入操作前，先列出几个高频误区，帮助你在后续章节中保持警觉。
| 误区 | 典型表现 | 正确做法 |
|---|---|---|
| 全局安装 Qiskit | 所有项目共用一个 site-packages，升级后旧项目报错 | 每个项目创建独立虚拟环境 |
| 混用 pip 与 conda 安装同一包 | 依赖冲突、包被覆盖、环境损坏 | 同一环境内选定一种包管理器为主 |
| 不记录版本 | 换机器后 pip install qiskit 拉到新版本，代码跑不通 | 用 requirements.txt 或 environment.yml 锁定版本 |
误以为 qiskit 是单一包 | 找不到 qiskit_aer 模块 | 理解元包与分件关系，按需安装子包 |
| 忽略 Python 版本约束 | 安装时报 “No matching distribution” | 先确认 Python 版本满足 Qiskit 要求 |
python -c "import qiskit; print(qiskit.__version__)"。如果这条命令能打印出版本号，说明当前解释器、虚拟环境和 Qiskit 安装三者是一致的；如果报错，问题一定出在这条链路的某一环，按“解释器路径 → 虚拟环境是否激活 → 包是否安装”的顺序排查即可。接下来的章节将从最基础的 Python 安装讲起，逐步搭建起一套可复现、可迁移的 Qiskit 开发环境。请把本节的三层目标——装得上、跑得通、管得住——作为贯穿全课程的自检标准。