学完这一课，你的浏览器里会跑起 Reflex 的默认应用，你也能用一句话说清楚 Reflex 是如何把 Python 代码变成 Web 应用的。

1-1. Reflex 是什么（10 分钟）

一个 Web 应用通常分为两部分：

• 前端：在浏览器中运行的界面，通常用 HTML、CSS、JavaScript（React 等）编写。
• 后端：在服务器上运行的逻辑和数据，通常用 Python（Django、FastAPI）等编写。

一般来说，两种语言都得学，还要在两者之间设计 API。Reflex 是一个全栈框架，让你前端和后端都用 Python 来写。

它的工作原理分为三步：

1. 编译：在应用启动时，把构建界面的 Python 函数（组件）执行一次，转换成 React 代码。生成的结果存放在 .web/ 文件夹中。
2. 状态在服务器上：数据（State）和事件处理函数都在服务器端的 Python 中运行。
3. 通过 WebSocket 同步：点击按钮时，浏览器把事件发给服务器，服务器只返回发生变化的状态，界面随之自动重新渲染。

左边的一个 Python 文件分成两路：界面函数被编译成 React 发送到浏览器，State 则留在服务器上，通过 ②→③ 的往返与界面保持同步。

1-2. 准备开发环境（10 分钟）

安装 uv：uv 是一个能同时管理 Python 版本、虚拟环境和依赖包的工具。

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

检查 Node.js：Reflex 使用 Node.js 或 Bun 来安装和运行界面端（React）的依赖包。Reflex 0.10 要求 Node 22.22.0 及以上。

node -v   # 需要 v22.22.0 及以上

1-3. 创建并运行项目（10 分钟）

uv init tutorial_261019        # 创建 Python 项目
cd tutorial_261019
uv add reflex                  # 安装 reflex（记录到 pyproject.toml）
uv run reflex init             # 生成 Reflex 应用骨架（选择模板）
uv run reflex run              # 启动开发服务器

• uv run 会在项目的虚拟环境（.venv）中执行命令，不需要手动激活虚拟环境。
• reflex init 会询问使用哪个模板。如果想从空白应用开始，也可以直接指定，例如 uv run reflex init --template blank。
• reflex run 启动完成后，用浏览器打开日志中 App running at: http://localhost:3000 的地址。如果 3000 端口已被占用，会自动换成 3001 等端口。
• 默认情况下，前端运行在 3000 端口，后端运行在 8000 端口。
• 首次运行需要下载界面相关的依赖包，可能要 1~3 分钟，并且需要联网。
• 要停止服务器，在终端中按 Ctrl + C。

在浏览器中确认 — 用 --template blank 创建完成后打开 http://localhost:3000，应该能看到下面的界面。右上角的太阳图标是深色模式切换按钮。

1-4. Windows 上常见的 2 个错误（5 分钟）

这是准备课程时真实遇到的问题。学员很可能也会碰到，请提前提醒。

• 用 setx 设置的环境变量只对新打开的终端生效。如果用的是 VS Code 终端，需要把 VS Code 也重新打开。
• 如果 winget 提示“找不到已安装的程序包”，用 winget list --name Node 查看实际的包 ID。

检查点

• node -v 显示 22.22.0 及以上。
• 运行 uv run reflex run 后，浏览器中能看到默认界面。
• 能用自己的话解释“界面函数只编译一次，事件函数每次都在服务器上执行”。