# FastAPI Test Project## 项目简介
这是一个使用 FastAPI 框架的测试项目。## 技术栈
- Python >= 3.13
- FastAPI >= 0.121.2
- Uvicorn >= 0.38.0
- uv (包管理工具)## 环境配置### 虚拟环境说明
本项目使用 **uv** 工具管理虚拟环境和依赖。uv 创建的虚拟环境更加精简高效,但默认不包含 pip。### 创建和激活虚拟环境
```bash
# 创建虚拟环境
uv venv# 激活虚拟环境
source .venv/bin/activate
依赖管理
使用 uv 管理依赖(推荐)
# 安装所有依赖
uv sync# 添加新依赖
uv add package_name# 移除依赖
uv remove package_name# 查看已安装的包
uv pip list
在虚拟环境中安装 pip
如果你需要使用传统的 pip 命令,可以手动安装:
推荐方法: 使用 get-pip.py(最可靠)
# 1. 激活虚拟环境
source .venv/bin/activate# 2. 下载 get-pip.py(等待下载完成,不要中断)
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py# 3. 安装 pip
python get-pip.py# 4. 清理下载文件
rm get-pip.py# 5. 重新激活虚拟环境以更新 PATH
deactivate
source .venv/bin/activate# 6. 验证 pip 已正确安装到虚拟环境
which pip
# 应该显示: /Users/peter/home/fastapi_test/.venv/bin/pippip --version
pip list
备选方法: 使用 ensurepip
# 激活虚拟环境后执行
python -m ensurepip --upgrade# 重新激活虚拟环境
deactivate
source .venv/bin/activate# 验证
which pip
pip --version
注意事项:
- 安装 pip 后必须重新激活虚拟环境,否则
which pip可能还指向系统 pip - 下载 get-pip.py 时不要中断,确保文件完整下载
- 如果下载速度慢,可以使用国内镜像:
curl https://mirrors.tuna.tsinghua.edu.cn/pypi/web/packages/get-pip.py -o get-pip.py
运行项目
运行主程序
python main.py
运行 FastAPI 服务(待实现)
uvicorn main:app --reload
项目结构
fastapi_test/
├── .venv/ # 虚拟环境目录
├── main.py # 主程序入口
├── pyproject.toml # 项目配置和依赖声明
├── uv.lock # uv 依赖锁定文件
└── README.md # 项目说明文档
常见问题
Q: 为什么虚拟环境中没有 pip?
A: uv 创建的虚拟环境不包含 pip,因为 uv 本身就是包管理工具。如果需要使用 pip,请按照上面的步骤手动安装。
Q: 安装 pip 后 which pip 还是指向系统 pip?
A: 需要重新激活虚拟环境来更新 PATH 环境变量:
deactivate
source .venv/bin/activate
which pip # 现在应该指向虚拟环境内的 pip
如果重新激活后还是不行,检查 shell 配置文件:
# 查看是否有重复的 PATH 设置
grep -n "PATH.*local" ~/.zshrc# 确保 .local/bin 不在最前面
# 错误示例: export PATH="/Users/peter/.local/bin:$PATH"
# 正确示例: export PATH="$PATH:/Users/peter/.local/bin"
Q: 为什么需要重新激活虚拟环境?
A: 因为 activate 脚本在激活时会扫描 .venv/bin/ 目录并设置 PATH。安装 pip 后,bin 目录新增了 pip 可执行文件,但 PATH 已经设置好了不会自动更新。重新激活会让 shell 重新扫描并更新 PATH。
Q: 如何查看已安装的包?
A: 使用以下命令:
# 使用 uv
uv pip list# 使用 pip(如果已安装)
pip list# 使用 python 模块方式(总是使用虚拟环境的 pip)
python -m pip list
Q: get-pip.py 下载失败或报错?
A:
- 确保下载完整,不要中断下载过程
- 如果出现
SyntaxError: unterminated triple-quoted string,说明文件下载不完整,重新下载 - 使用国内镜像加速下载:
curl https://mirrors.tuna.tsinghua.edu.cn/pypi/web/packages/get-pip.py -o get-pip.py
Q: 使用 venv 创建虚拟环境时报错?
A: 如果遇到 ensurepip 错误,使用 --without-pip 参数创建虚拟环境,然后手动安装 pip:
python3 -m venv .venv --without-pip
source .venv/bin/activate
python -m ensurepip --upgrade
deactivate && source .venv/bin/activate
故障排查
检查虚拟环境状态
# 激活虚拟环境
source .venv/bin/activate# 检查 Python 路径
which python
# 应该显示: /Users/peter/home/fastapi_test/.venv/bin/python# 检查 pip 路径
which pip
# 应该显示: /Users/peter/home/fastapi_test/.venv/bin/pip# 检查 PATH 前几项
echo $PATH | tr ':' '\n' | head -5
# 第一项应该是虚拟环境的 bin 目录# 检查虚拟环境变量
echo $VIRTUAL_ENV
# 应该显示: /Users/peter/home/fastapi_test/.venv# 列出虚拟环境 bin 目录内容
ls -la .venv/bin/ | grep -E "(pip|python)"
Shell 配置问题
如果 PATH 顺序不正确,检查 ~/.zshrc 或 ~/.zprofile:
# 查看 PATH 相关配置
cat ~/.zshrc | grep -i path# 确保没有重复设置 .local/bin 在最前面
# 删除或注释掉类似这样的行:
# export PATH="/Users/peter/.local/bin:$PATH"# 保留这样的设置(把 .local/bin 放在最后):
# export PATH="$PATH:/Users/peter/.local/bin"
开发计划