跳到主要内容

1.2 环境搭建与安装

本节目标：装好 Python 环境和所有依赖包，为整个教程做好准备。全程大约 10 分钟。

一、确认 Python 版本​

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

python --version

要求 Python 3.10 或以上（本教程的类型注解语法需要）。如果版本过低或未安装，去 python.org 下载最新版。

💡 Windows 安装时务必勾选 "Add Python to PATH"。

二、创建项目目录和虚拟环境​

虚拟环境是 Python 的标准做法：给每个项目一个独立的包环境，避免不同项目的依赖互相打架。

# 1. 创建项目目录
mkdir sqlalchemy-learn
cd sqlalchemy-learn

# 2. 创建虚拟环境（会生成一个 .venv 文件夹）
python -m venv .venv

激活虚拟环境（每次打开新终端都要做这一步）：

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

# Mac / Linux
source .venv/bin/activate

激活成功后，命令行前面会出现 (.venv) 前缀。

⚠️ Windows PowerShell 报错 "禁止运行脚本"？ 以管理员身份打开 PowerShell 执行一次：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新激活即可。

三、安装依赖包​

在已激活虚拟环境的终端里执行：

pip install sqlalchemy "fastapi[standard]" alembic aiosqlite

各包的作用：

包名作用用到的章节
sqlalchemy本教程主角全部
fastapi[standard]Web 框架（含 uvicorn 服务器、pydantic）第6、7章
alembic数据库迁移工具（SQLAlchemy 官方出品）5.3 节
aiosqliteSQLite 的异步驱动5.4 节

验证安装：

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

输出 2.0.x 即成功（必须是 2.0 以上）。

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

四、关于数据库：为什么不用装 MySQL？​

本教程使用 SQLite 作为数据库。它的特别之处：

  • 不是一个"服务器软件"，而是一个嵌入式库，数据就存在一个 .db 文件里
  • Python 标准库自带驱动（sqlite3 模块），零安装
  • SQLAlchemy 对它完美支持

将来切换到 MySQL / PostgreSQL 有多简单？ 只需两步：

# 1. 装对应驱动
pip install pymysql          # MySQL
pip install psycopg2-binary  # PostgreSQL
# 2. 改一行连接字符串（2.1 节详讲）
# SQLite:
engine = create_engine("sqlite:///app.db")
# MySQL:
engine = create_engine("mysql+pymysql://user:password@localhost:3306/mydb")
# PostgreSQL:
engine = create_engine("postgresql+psycopg2://user:password@localhost:5432/mydb")

其余所有 ORM 代码一行都不用改。这就是 ORM 抹平数据库差异的威力。

五、推荐的开发工具​

工具说明
VS Code + Python 扩展免费、轻量，装上 Pylance 后类型提示极佳
PyCharm功能全面的 Python IDE，社区版免费
DB Browser for SQLite图形化查看 .db 文件内容，强烈推荐装一个，学习时能直观看到表里的数据（下载地址）

💡 SQLAlchemy 2.0 的一大优势是完整的类型注解支持。在 VS Code / PyCharm 里，user. 按下去会自动提示 name、email 等字段，写错字段名立刻标红。这是老版本没有的体验。

六、锁定依赖（好习惯）​

把当前依赖版本记录到文件里，方便以后在别的机器还原环境：

pip freeze > requirements.txt

以后任何人（包括未来的你）只需：

pip install -r requirements.txt

✅ 环境自检清单​

在继续之前，确认以下各项都完成：

  • python --version ≥ 3.10
  • 虚拟环境已创建并激活（命令行有 (.venv) 前缀）
  • import sqlalchemy 版本为 2.0+
  • import fastapi 不报错
  • （可选）装好了 DB Browser for SQLite

全部通过？进入正题 → 1.3 第一个 SQLAlchemy 程序