环境搭建

方法论: 工具装好，代码能跑，就是成功。遇到问题复制报错问 AI。

📖 本节目标

学完本节，你将能够：

✅ 安装 Python 并验证
✅ 创建虚拟环境（隔离项目依赖）
✅ 配置 VS Code 开发环境
✅ 注册 Supabase 数据库
✅ 安装 API 测试工具

预计用时: 30 分钟

1. 安装 Python

1.1 为什么需要 Python？

Python = 后端的运行环境

就像你玩游戏需要安装游戏客户端一样，写 Python 代码也需要先安装 Python。

1.2 下载安装

推荐版本: Python 3.10 或 Python 3.11（稳定版）

Windows 用户:

访问 python.org/downloads
下载 Python 3.11.x 安装包（点击大按钮“Download Python 3.11.x“）
双击安装包
重要！ 勾选 ✅ “Add Python to PATH”（最下面的复选框）
点击 “Install Now”
等待安装完成

Mac 用户:

# 方式1: 使用 Homebrew（推荐）
brew install python@3.11

# 方式2: 官网下载安装包
访问 python.org/downloads
下载 macOS 安装包并安装

1.3 验证安装

第一步: 打开终端/命令行

什么是终端？ 终端 = 电脑的文字控制台，就像你和电脑用打字聊天一样。不用害怕，它不会弄坏你的电脑。

Windows 用户（3 种方法）:

按 Win + R 键，输入 cmd，按回车（最快）
点击开始菜单，搜索“命令提示符“或“cmd“
在任意文件夹按住 Shift，右键点击空白处，选择“在此处打开 PowerShell 窗口“

Mac 用户（2 种方法）:

按 Command + 空格，输入 Terminal，按回车（最快）
打开“启动台“，找到“其他“文件夹，点击“终端“

第二步: 验证 Python

在终端窗口输入：

python --version

或者（Mac/Linux 可能需要用 python3）：

python3 --version

成功的样子:

Python 3.11.5

如果报错 “command not found” 或 “不是内部或外部命令”:

重启终端再试一次
还不行，复制报错信息问 AI：

“我安装 Python 后输入 python –version 报错：[粘贴报错信息]”

2. 创建虚拟环境

2.1 什么是虚拟环境？

虚拟环境 = 每个项目的独立工作间

类比理解：

你有多个项目，每个项目需要不同版本的工具
项目 A 需要 FastAPI 0.100.0
项目 B 需要 FastAPI 0.95.0
如果都装在同一个地方，就会冲突
虚拟环境让每个项目有自己的工具箱

2.2 创建第一个项目

步骤1: 创建项目文件夹

建议: 先在桌面新建一个文件夹叫 my-backend，这样你能随时在“我的电脑“里找到它。

方式 A: 用鼠标操作（推荐新手）:

在桌面右键，新建文件夹，命名为 my-backend
进入这个文件夹
在文件夹空白处，按住 Shift + 右键（Windows）或直接右键（Mac），选择“在此处打开终端/命令行“

方式 B: 用命令行:

# 创建文件夹
mkdir my-backend
# 进入文件夹
cd my-backend

提示: 如果你用命令行创建，文件夹会在你当前打开终端的位置。不确定在哪？输入 pwd（Mac/Linux）或 cd（Windows）可以查看当前路径。

步骤2: 创建虚拟环境

# 创建虚拟环境（名字叫 venv）
python -m venv venv

等待几秒钟，会生成一个 venv 文件夹。

步骤3: 激活虚拟环境

Windows:

venv\Scripts\activate

Mac/Linux:

source venv/bin/activate

成功的样子:

命令行前面会出现 (venv) 标记：

(venv) C:\Users\你的名字\my-backend>

2.3 安装 FastAPI

激活虚拟环境后，安装 FastAPI：

pip install fastapi uvicorn[standard]

工具认知小贴士:

FastAPI = 写 API 的工具（就像 Word 是写文档的工具）

Uvicorn = 运行服务器的引擎（就像游戏需要引擎才能跑起来）

[standard] = 安装标准版（包含更多功能，新手直接用这个就行，不用管为什么）

等待安装完成（会显示一堆下载信息，这是正常的）。

如果下载很慢，配置国内镜像:

# 配置淘宝镜像（一次性设置）
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

# 再次安装
pip install fastapi uvicorn[standard]

验证安装:

pip list

应该能看到 fastapi 和 uvicorn 在列表里。

2.4 退出虚拟环境

deactivate

命令行前面的 (venv) 会消失。

3. 配置 VS Code

3.1 为什么选 VS Code？

VS Code = 最受欢迎的代码编辑器

✅ 免费开源
✅ 插件丰富
✅ 轻量快速
✅ 支持所有编程语言

3.2 下载安装

访问 code.visualstudio.com

点击大按钮下载，双击安装，一路“下一步“。

3.3 安装必备插件

打开 VS Code 后，点击左侧边栏的扩展图标（四个方块）。

必装插件（搜索名字安装）:

Python (Microsoft 官方)
- 作用：代码高亮、智能提示、调试
- 搜索 “Python”，点击 Install
Pylance (Microsoft 官方)
- 作用：类型检查、更好的代码补全
- 搜索 “Pylance”，点击 Install
Thunder Client (可选，但推荐)
- 作用：在 VS Code 里测试 API
- 搜索 “Thunder Client”，点击 Install
indent-rainbow (强烈推荐)
- 作用：缩进高亮（Python 必备！）
- 搜索 “indent-rainbow”，点击 Install

3.4 配置 Python 解释器

打开你的项目文件夹（my-backend）
- File → Open Folder → 选择 my-backend
打开任意 .py 文件（或新建一个 test.py）
按 Ctrl+Shift+P（Mac: Cmd+Shift+P）
输入 “Python: Select Interpreter”
选择带 (venv) 的那个选项
```
./venv/Scripts/python.exe
```

3.5 创建第一个 Python 文件

在 VS Code 中新建文件 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Hello World"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

代码解读 (不用背，让 AI 写就行):

前 7 行：定义了一个最简单的 API（返回 Hello World）

if __name__ == "__main__": 这 4 行：Python 的启动开关（就像电视机的电源开关，现在先别管为什么这么写，照抄就行）

想深入理解？ 复制这段代码问 AI：“这段代码每一行都是什么意思？”，AI 会给你详细解释。

运行代码:

在终端输入：

# 确保虚拟环境已激活（前面有 (venv)）
python main.py

成功的样子:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

打开浏览器，访问 http://localhost:8000

应该能看到：

{"message": "Hello World"}

恭喜！你的第一个 API 跑起来了！ 🎉

框架理解：整个流程是怎么运转的？

想象你开了一家餐厅（后端服务器）：

Python = 餐厅的地基（运行环境）

FastAPI = 餐厅的菜单系统（定义你提供什么服务）

Uvicorn = 餐厅的大门和收银台（接待客人的请求）

这段代码 = 你的第一道菜：“Hello World 套餐”

数据流向: 浏览器（客人）→ 输入网址 → Uvicorn（大门）→ FastAPI（菜单）→ 你的代码（厨师做菜）→ 返回结果（上菜）→ 浏览器显示

后面我们会加上 Supabase（仓库），这样数据就能永久存储了。

4. 注册 Supabase

4.1 什么是 Supabase？

Supabase = 免费的云数据库

不用自己搭建数据库服务器
提供可视化管理界面
免费额度：500MB 数据库 + 1GB 存储

4.2 注册账号

访问 supabase.com
点击 “Start your project”
选择 GitHub 账号登录（推荐）或邮箱注册

4.3 创建项目

登录后点击 “New Project”
填写信息：
- Name: 项目名称（如 my-backend-db）
- Database Password: 设置一个密码（记住它！）
- Region: 选择 Northeast Asia (Tokyo) 或 Southeast Asia (Singapore)
点击 “Create new project”
等待 2-3 分钟（会显示进度条）

4.4 获取连接信息

项目创建成功后：

点击左侧菜单 “Settings”（齿轮图标）
点击 “API”
找到这两个信息（后面会用到）：
- Project URL: https://xxx.supabase.co
- anon public key: 一串很长的字符串

妥善保存这两个信息:

重要！保存方法:
在桌面新建一个记事本文件（或用 VS Code 新建），命名为 supabase-secrets.txt
把这两个信息粘贴进去，格式如下：
Project URL: https://xxx.supabase.co
Anon Key: eyJhbGci...（一串很长的字符）
保存好，不要分享给别人

这个文件放在项目文件夹里就行，以后需要用的时候直接复制
安心提示: 如果不小心关了网页，随时可以回到 Supabase 项目的 Settings → API 重新查看。

4.5 创建第一张表

点击左侧菜单 “Table Editor”
点击 “Create a new table”
填写表信息：
- Name: users（表名）
- 保留默认字段（id, created_at）
- 点击 “Add column” 添加新字段：
  - username (type: text, unique: ✅)
  - email (type: text)
  - password_hash (type: text)
点击 “Save”

成功！你已经有了第一张数据库表！ 🎉

5. 安装 API 测试工具

5.1 为什么需要测试工具？

测试工具 = 模拟前端发请求

你写了一个注册接口 POST /api/users/register
但前端还没写好
测试工具可以直接发请求测试接口

5.2 选择一：FastAPI 自带文档（最简单，推荐新手）

无需安装！ 运行 FastAPI 后直接访问：

http://localhost:8000/docs

会看到自动生成的 API 文档，可以直接测试。

5.3 选择二：Postman（功能强大）

新手要不要装？ 可以先跳过！用 FastAPI 自带的 /docs 或 VS Code 的 Thunder Client 插件就够了。Postman 功能很强，但对新手来说有点复杂。等你熟练了再装也不迟。

下载安装:

访问 postman.com/downloads
下载并安装
注册账号（免费）

创建第一个请求:

点击 “New” → “HTTP Request”
选择方法：POST
输入 URL：http://localhost:8000/api/users/register
点击 “Body” → 选择 “raw” → 选择 “JSON”

输入数据：

{
  "username": "zhangsan",
  "password": "123456",
  "email": "zhang@example.com"
}

点击 “Send”

5.4 选择三：Thunder Client（VS Code 插件，推荐）

安装:

在 VS Code 扩展商店搜索 “Thunder Client”，点击 Install。

使用:

左侧边栏出现 ⚡ 图标
点击 “New Request”
和 Postman 类似操作

6. 快速检查清单

完成后，检查这些：

终端输入 python --version 能显示版本号
能创建并激活虚拟环境（命令行前有 (venv)）
pip list 能看到 fastapi 和 uvicorn
VS Code 能打开并运行 Python 代码
访问 http://localhost:8000 能看到 “Hello World”
Supabase 项目已创建，能看到 users 表
能用 /docs 或 Postman 测试 API

全部✅？恭喜你，开发环境搭建完成！ 🎉

7. 常见问题

Q1: pip install 很慢怎么办？

A: 配置国内镜像

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

Q2: python –version 提示 “command not found”

Windows: 重新安装 Python，勾选 “Add Python to PATH”

Mac: 改用 python3 --version，或安装 Homebrew 后用 brew install python@3.11

Q3: 虚拟环境激活后命令行没有 (venv) 标记

可能是激活成功了但没显示。试试安装 FastAPI：

pip install fastapi

如果能安装，说明激活成功了。

Q4: VS Code 找不到 Python 解释器

按 Ctrl+Shift+P
输入 “Python: Select Interpreter”
点击 “Enter interpreter path”
手动输入虚拟环境 Python 路径：
- Windows: ./venv/Scripts/python.exe
- Mac/Linux: ./venv/bin/python

Q5: Supabase 项目创建失败

检查网络连接
换个浏览器试试
重新注册账号
还不行就复制报错问 AI

💡 Vibe Coding 提示

如果你遇到了上面没提到的问题：

复制完整报错信息（不要只复制一部分）
- 看到红色文字不要慌，这是电脑在告诉你哪里需要调整
- 报错信息是 AI 的重要线索，要全部复制

问 AI 的正确姿势：

我在 [安装Python/配置VS Code/创建Supabase] 时遇到这个错误：
[粘贴完整报错信息]

我的系统是：[Windows 11 / macOS 等]
我已经尝试了：[你做过的操作]

按照 AI 的建议一步步操作
- 一次只做一个修改
- 每次修改后测试是否有效
- 如果不行，告诉 AI 结果，让它给新方案
还不行就换个方式
- 比如 Python 官网下载不了就用 Homebrew
- pip 安装慢就配置国内镜像
- VS Code 有问题可以试试重启电脑

AI 协作核心:

你只需要理解做什么（装 Python、创建虚拟环境、运行代码）

具体怎么做（命令、代码、配置）都可以问 AI

验证方法：运行代码，看到预期结果（如 Hello World）就说明成功了

记住: 工具只是手段，能跑起来就行。不要在环境配置上花太多时间。如果卡住超过 30 分钟，直接把问题发给 AI，让它帮你解决。

📚 下一步

👉 第一个接口

从 Hello World 到用户注册，写出第一个真正可用的 API。

返回后端开发基础查看完整目录。

Keyboard shortcuts

Vibe Coding 实战手册