跳到主要内容

02 环境搭建

本章目标：装好 Python，创建项目目录和虚拟环境，安装 FastAPI 相关依赖。

1. 安装 Python​

FastAPI 需要 Python 3.8+，本教程建议使用 3.11 或 3.12。

Windows​

  1. 打开 https://www.python.org/downloads/ 下载最新的 Python 3.12 安装包
  2. 运行安装程序，务必勾选 Add Python to PATH（这是新手最容易漏掉的一步）
  3. 一路 Next 安装完成

macOS​

# 推荐用 Homebrew 安装
brew install python@3.12

验证安装​

打开终端（Windows 用 PowerShell 或 CMD，Mac 用 Terminal），输入：

python --version
# 或者在 Mac/Linux 上可能是
python3 --version

看到 Python 3.12.x 之类的输出就说明装好了。

注意：Windows 上如果提示「python 不是内部或外部命令」，说明没勾选 Add to PATH，重新安装并勾选即可。

2. 创建项目目录​

选一个你放代码的地方，创建项目文件夹：

# Windows (PowerShell)
mkdir D:\projects\fastapi-tutorial
cd D:\projects\fastapi-tutorial

# macOS / Linux
mkdir -p ~/projects/fastapi-tutorial
cd ~/projects/fastapi-tutorial

后面所有命令都默认在这个目录下执行。

3. 创建虚拟环境（重要！）​

为什么需要虚拟环境？​

不同项目可能依赖同一个库的不同版本。虚拟环境相当于给每个项目一个独立的 Python 包空间，互不干扰。这是 Python 开发的标准做法，请养成习惯：每个项目都建一个虚拟环境。

创建​

python -m venv venv

这会在项目目录下生成一个 venv 文件夹（就是虚拟环境本体，不要提交到 git）。

激活​

# Windows PowerShell
venv\Scripts\Activate.ps1

# Windows CMD
venv\Scripts\activate.bat

# macOS / Linux
source venv/bin/activate

激活成功后，命令行前面会出现 (venv) 字样：

(venv) PS D:\projects\fastapi-tutorial>

Windows PowerShell 报错？ 如果提示「禁止运行脚本」，以管理员身份打开 PowerShell 执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新激活即可。

**以后每次打开新终端做这个项目，都要先激活虚拟环境。**退出虚拟环境用 deactivate 命令。

4. 安装 FastAPI 和相关依赖​

确保命令行前面有 (venv)，然后执行：

pip install "fastapi[standard]" sqlalchemy

这条命令安装了：

包作用
fastapi框架本体
uvicornASGI 服务器，负责真正运行你的程序（standard 附带）
pydantic数据校验（FastAPI 依赖，自动安装）
sqlalchemyORM，第三部分开始使用

如果下载很慢，可以用国内镜像：

pip install "fastapi[standard]" sqlalchemy -i https://pypi.tuna.tsinghua.edu.cn/simple

验证安装​

pip list

能看到 fastapi、uvicorn、sqlalchemy 等包就 OK 了。

5. 记录依赖（好习惯）​

把当前依赖导出到文件，方便以后在别的机器上重建环境：

pip freeze > requirements.txt

别人（或未来的你）拿到项目后，只需要：

pip install -r requirements.txt

6. 选择代码编辑器​

推荐 VS Code（免费）：

  1. 下载安装：https://code.visualstudio.com/
  2. 安装扩展：Python（微软官方）和 Pylance
  3. 打开项目文件夹：File → Open Folder
  4. 按 Ctrl+Shift+P 输入 Python: Select Interpreter，选择 venv 里的那个 Python —— 这样编辑器才能正确识别你装的包

PyCharm 也很好，社区版免费，装好后同样把解释器指向项目的 venv。

7. 最终检查清单​

  • python --version 显示 3.10 以上
  • 项目目录已创建
  • 虚拟环境已创建且能激活（命令行有 (venv) 前缀）
  • pip list 里有 fastapi、uvicorn、sqlalchemy
  • 编辑器已选择 venv 里的解释器

全部打勾？进入下一章：03-第一个API程序，写代码！