前端手摸手跑路之 AI 应用开发（一）

搭建 Vue 3 + FastAPI 项目环境

我准备做一个 AI 全栈学习项目，用它串起前端、后端、数据库和后面的 AI 功能，为转（run）型（away）做准备

第一步没有急着写业务代码，而是先把开发环境和项目骨架搭好

这一阶段看起来只是安装工具和创建目录，实际最容易留下环境混乱、依赖不可复现、换电脑就跑不起来这些问题

本文记录一次 Windows 环境下的真实搭建过程，也整理几个当时容易混淆的概念

最终技术栈

前端使用：

text 复制代码

Node.js
→ pnpm
→ Vite
→ Vue 3
→ TypeScript

后端使用：

text 复制代码

64 位 Python 3.12
→ uv
→ FastAPI

最终目录大致如下：

text 复制代码

ai-workspace/
├─ frontend/                 Vue 3 + TypeScript + Vite
├─ backend/                  Python + FastAPI + uv
│  ├─ .python-version
│  ├─ .venv/
│  ├─ pyproject.toml
│  ├─ uv.lock
│  └─ app/
├─ docs/
└─ .gitignore

一、创建 Vue 项目

在项目根目录创建前端：

powershell 复制代码

pnpm create vite frontend --template vue-ts
cd frontend
pnpm install

这里选择 vue-ts 模板，让项目从一开始就使用 Vue 3 和 TypeScript，为什么使用 pnpm，不需要我多bb

常用命令都定义在 frontend/package.json 中：

powershell 复制代码

pnpm dev
pnpm build
pnpm preview

它们分别用于本地开发、生产构建和预览构建结果

本项目的 build 脚本会先执行 Vue 和 TypeScript 类型检查，再让 Vite 生成生产文件

json 复制代码

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview"
  }
}

二、使用 uv 管理 Python 后端

以前搭 Python 项目时，我习惯先安装 Python，再创建虚拟环境，然后用 pip 安装依赖

这次改用 uv 统一处理 Python 版本、虚拟环境、依赖声明和锁文件

安装 uv

Windows 可以通过 WinGet 安装：

powershell 复制代码

winget install --id=astral-sh.uv -e

也可以使用官方 PowerShell 安装脚本：

powershell 复制代码

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，需要重新打开终端，再确认版本：

powershell 复制代码

uv --version

如果外部 PowerShell 能找到 uv，但 VS Code 终端提示命令不存在，通常不是安装失败

原因是 VS Code 仍然使用启动时继承的旧 PATH，完全退出并重新打开 VS Code 即可

安装并选择 Python

这个项目最初固定为 64 位 Python 3.12：

powershell 复制代码

uv python install 3.12
uv python find 3.12

uv python find 3.12 会输出实际使用的 Python 路径，可以顺便确认没有误用旧的 32 位解释器

初始化后端

powershell 复制代码

mkdir backend
cd backend
uv init --no-package --python 3.12

这里使用 --no-package，因为本文项目采用 backend/app 目录组织 FastAPI 代码，不需要 uv 额外生成 src/backend 包结构

新版 uv 默认会创建 packaged application，生成 src/<项目名>、构建系统和命令入口，这也是一种合理结构，但不应和本文的 app 结构混用

接着创建应用目录

powershell 复制代码

mkdir app
New-Item app\__init__.py -ItemType File

然后加入 FastAPI：

powershell 复制代码

uv add "fastapi[standard]"

fastapi[standard] 除了 FastAPI 本身，还包含开发服务器和常用标准依赖

执行后，uv 会创建或更新以下内容：

text 复制代码

.python-version
.venv/
pyproject.toml
uv.lock

三、四个文件分别解决什么问题

第一次看到这些文件时，很容易把它们都理解成环境配置

实际上，它们的职责不同：

`.python-version`

记录项目优先使用的 Python 版本：

text 复制代码

3.12

它解决的是选择哪个 Python 解释器的问题

`.venv`

保存当前电脑上的项目虚拟环境，第三方依赖实际安装在这里

它属于可以重新生成的本地内容，不应该提交到 Git

`pyproject.toml`

声明项目元数据、Python 版本范围和直接依赖

最初的依赖只有 FastAPI：

toml 复制代码

[project]
name = "backend"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]>=0.141.1",
]

这里记录的是项目主动需要什么

`uv.lock`

锁定完整依赖树的具体版本

FastAPI 还会依赖 Starlette、Pydantic 等包，锁文件会把这些间接依赖一起记录下来

它解决的是不同电脑和不同时间安装时结果尽量一致的问题

可以把四者记成：

text 复制代码

.python-version
→ 选择 Python

pyproject.toml
→ 声明直接依赖

uv.lock
→ 固定完整依赖树

.venv
→ 保存本机实际安装结果

四、为什么推荐使用 `uv run`

启动后端时可以手动激活虚拟环境，但这不是必需步骤

项目中更常用：

powershell 复制代码

uv run <命令>

例如：

powershell 复制代码

uv run python --version
uv run fastapi --help
uv run fastapi dev app/main.py

uv run 会读取当前项目配置，并在项目对应的环境中执行后面的命令

这样不需要反复执行激活和退出虚拟环境的命令，也能减少在错误环境里运行程序的情况

需要注意，激活 .venv 不代表系统一定能找到 uv.exe

.venv 是项目运行环境，uv 是单独安装的项目管理工具，两者不是同一个东西

五、`.venv` 和 `pycache` 不是一类东西

这两个目录都可以重新生成，但用途完全不同：

text 复制代码

.venv
→ 保存 Python 环境和第三方依赖

__pycache__
→ 保存 Python 导入模块时生成的字节码缓存

删除 .venv 后，需要重新同步依赖：

powershell 复制代码

uv sync

删除 __pycache__ 后不需要恢复操作，Python 下次运行时会自动生成

两者都不应该提交到 Git

六、配置 Git 忽略规则

项目根目录使用统一的 .gitignore：

gitignore 复制代码

# Python generated files and environments
__pycache__/
*.py[cod]
.venv/
.pytest_cache/
.mypy_cache/
.ruff_cache/

# Local environment variables and secrets
.env
.env.*
!.env.example

# Frontend generated files
node_modules/
dist/
dist-ssr/

# Logs and operating-system files
*.log
.DS_Store
Thumbs.db

这里忽略的是可以重新生成的环境、缓存、构建产物和本地秘密

pyproject.toml、uv.lock、package.json 和前端锁文件需要提交，它们是恢复环境的重要依据

七、已有项目如何恢复环境

换电脑或重新拉取仓库后，不需要复制旧电脑的 .venv 和 node_modules

恢复后端：

powershell 复制代码

cd backend
uv sync

恢复前端：

powershell 复制代码

cd frontend
pnpm install

背后的逻辑是：

text 复制代码

后端
pyproject.toml + uv.lock
→ uv sync
→ 重建 .venv

前端
package.json + pnpm-lock.yaml
→ pnpm install
→ 重建 node_modules

真正需要保存的是声明和锁文件，不是本机生成的依赖目录

八、日常启动顺序

项目加入 PostgreSQL 后，日常开发按数据库、后端、前端的顺序启动

我通常在 VS Code 中打开三个终端：

终端一启动 PostgreSQL

powershell 复制代码

cd D:\code\ai-workspace
docker compose up -d
docker compose ps

docker compose ps 中 PostgreSQL 应显示为 Up

终端二启动 FastAPI

powershell 复制代码

cd D:\code\ai-workspace\backend
uv run fastapi dev app/main.py

常用地址：

text 复制代码

API       http://127.0.0.1:8000
Swagger   http://127.0.0.1:8000/docs
数据库检查 http://127.0.0.1:8000/api/health/database

开发服务器会持续占用当前终端，这是正常状态

需要执行其他命令时新开终端，不要重复启动后端

终端三启动 Vue

powershell 复制代码

cd D:\code\ai-workspace\frontend
pnpm dev

前端默认地址：

text 复制代码

http://localhost:5173

停止项目

前端和后端分别在对应终端按 Ctrl+C

数据库可以执行：

powershell 复制代码

docker compose stop

stop 只停止容器，不删除容器和命名 volume，下一次仍可通过 docker compose up -d 启动

九、常见问题速查

VS Code 终端找不到 uv

完全退出并重新打开 VS Code，让新进程读取最新 PATH

后端提示缺少依赖

确认当前目录是包含 pyproject.toml 的后端目录，再执行

powershell 复制代码

uv sync

8000 端口被占用

先检查后端是否已经在另一个终端运行，不要遇到端口冲突就直接修改项目端口

阶段结果

到这里完成了几件事：

Vue 3、TypeScript 和 Vite 前端已经创建
后端使用 uv 管理 Python 和依赖
FastAPI 已写入项目依赖声明
前后端都具备可复现的锁文件
本地环境、缓存和构建产物已经排除在 Git 之外
已经能够分别启动前端和后端开发服务器

这一步还没有涉及具体业务，但项目已经具备继续开发的基础

后面增加数据库、用户接口和 AI 功能时，依赖和运行环境仍然沿用这一套管理方式

前端手摸手跑路之 AI 应用开发（一）

搭建 Vue 3 + FastAPI 项目环境

最终技术栈

一、创建 Vue 项目

二、使用 uv 管理 Python 后端

安装 uv

安装并选择 Python

初始化后端

三、四个文件分别解决什么问题

.python-version

.venv

pyproject.toml

uv.lock

四、为什么推荐使用 uv run

五、.venv 和 __pycache__ 不是一类东西

六、配置 Git 忽略规则

七、已有项目如何恢复环境

八、日常启动顺序

终端一启动 PostgreSQL

终端二启动 FastAPI

终端三启动 Vue

停止项目

九、常见问题速查

VS Code 终端找不到 uv

后端提示缺少依赖

8000 端口被占用

阶段结果

`.python-version`

`.venv`

`pyproject.toml`

`uv.lock`

四、为什么推荐使用 `uv run`

五、`.venv` 和 `pycache` 不是一类东西