1. 课程导入与Qiskit环境搭建

欢迎进入《Qiskit量子门操作与电路构建》课程。本课程的目标不是停留在量子计算的抽象概念上，而是让你能够真正动手：用Python和Qiskit把量子门"写"进电路，把电路"跑"在模拟器或真实设备上，并读懂结果。整个课程围绕一条主线展开——量子门是基本积木，量子电路是积木的搭法，Qiskit是搭建与验证的工具。后续章节会依次覆盖单量子比特门、多量子比特门与纠缠、测量与态制备、电路可视化、参数化电路与简单算法模块，最终能够独立构建并调试中等规模的量子电路。

本章作为开篇，要解决三个问题：环境能不能跑起来、第一个电路长什么样、结果怎么读。这三件事看似基础，却是后续所有实验的前提。很多初学者卡在安装和版本冲突上，因此我们先把环境讲清楚，再运行一个最小但完整的示例。

一、安装Qiskit与版本管理

Qiskit自1.0版本起进行了模块化重构，核心包qiskit包含量子电路构建与基础原语，而模拟器后端、可视化扩展等被拆分到独立包中。因此安装时建议使用虚拟环境隔离，避免与系统Python或其他项目冲突。推荐使用conda或venv创建独立环境，Python版本选择3.9至3.12之间较为稳妥。

# 创建并激活虚拟环境（以conda为例）
conda create -n qiskit-env python=3.11
conda activate qiskit-env

# 安装Qiskit核心包与常用扩展
pip install qiskit qiskit-aer

其中qiskit-aer是高性能模拟器后端，后续运行电路时会用到。安装完成后，务必检查版本，因为不同版本的API存在差异，尤其是1.x与0.x之间变化较大。可以用下面的命令确认：

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

如果输出类似1.2.4，说明核心包安装成功。建议在项目开始时固定版本，例如在requirements.txt中写明qiskit==1.2.4，这样团队协作或换机复现时不会因版本漂移导致代码报错。这是工程实践中非常容易被忽视、却经常引发"我这里能跑你那里报错"的关键点。

二、Jupyter Notebook配置

本课程示例以Jupyter Notebook为主要载体，便于分步执行、即时查看电路图和结果。安装与启动方式如下：

pip install notebook
jupyter notebook

启动后浏览器会打开工作目录。新建Notebook时，需要确保内核选择的是刚才创建的qiskit-env环境。若内核列表中没有该环境，可安装ipykernel并注册：

pip install ipykernel
python -m ipykernel install --user --name qiskit-env --display-name "Python (Qiskit)"

配置完成后，在Notebook中执行import qiskit不报错，即说明内核与环境匹配正确。建议每个实验Notebook的第一格都放版本检查代码，形成习惯。

三、运行第一个量子电路

下面构建一个最经典的示例：对单个量子比特施加Hadamard门，使其从|0⟩变为叠加态，然后测量。这个电路虽小，却完整包含了"建电路—加门—测量—运行—读结果"的全流程。

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

# 1. 创建1个量子比特、1个经典比特的电路
qc = QuantumCircuit(1, 1)

# 2. 施加Hadamard门，制备叠加态
qc.h(0)

# 3. 测量量子比特0，结果存入经典比特0
qc.measure(0, 0)

# 4. 使用Aer模拟器运行1024次
simulator = AerSimulator()
job = simulator.run(qc, shots=1024)
result = job.result()
counts = result.get_counts()
print(counts)

典型输出形如{'0': 512, '1': 512}左右（具体数值每次略有波动）。这里的含义是：Hadamard门把|0⟩变成 (|0⟩+|1⟩)/√2，测量时以约各50%的概率得到0或1。由于是概率性结果，1024次采样得到的比例不会精确等于50%，而是在其附近波动，这正体现了量子测量的统计特性。判断电路是否正确，关键看两点：一是结果只出现0和1两个键，说明测量映射正确；二是两者比例接近1:1，说明叠加态制备成功。若出现比例严重偏离，应检查是否误加了其他门或测量对象写错。

四、本节知识结构

下图把本节的环境搭建与首个电路运行过程组织为一条从工具准备到结果判读的链路，帮助你建立"环境—代码—电路—结果"的整体认识。

从图中可以看到，环境准备阶段（蓝色）解决的是"工具可用"，电路构建阶段（绿色）解决的是"逻辑正确"，结果判读阶段（橙色）解决的是"验证有效"。三者缺一不可。实际学习中，如果get_counts()返回空字典或报错，优先回查环境与后端是否匹配；如果结果只有单一键值，则回查门是否真正施加、测量映射是否正确。

五、常见问题与建议

• 导入报错：多为内核未切换到目标环境，或qiskit-aer未安装。先确认import qiskit_aer是否成功。
• 版本不一致：1.x版本中部分旧接口已移除，遇到AttributeError时先核对官方迁移说明，不要盲目降级。
• 结果波动：采样次数越少，比例波动越大。教学示例用1024次已足够观察趋势，若需更稳定统计可提高到4096次。

完成本节后，你应当能够独立创建环境、启动Notebook、构建并运行一个含Hadamard门与测量的单比特电路，并能根据计数结果判断叠加态是否制备成功。这套"环境—电路—运行—判读"的基本功，将贯穿后续所有量子门与电路实验。