Reflex 新手指南：5 条命令跑通第一个纯 Python Web 应用
【免费下载链接】reflex🕸️ Web apps in pure Python 🐍项目地址: https://gitcode.com/GitHub_Trending/re/reflex
Reflex 是一个用纯 Python 构建全栈 Web 应用的框架：前端和后端都写.py文件，不需要写 JavaScript。它在本地把你的 Python 组件编译成 React 前端，开发时保存代码即热重载。读完这篇指南，你会得到一个跑在http://localhost:3000的空白应用，并清楚哪些文件能改、哪些文件不能碰。环境要求只有一条：Python 3.10+，安装细节可查 docs/getting_started/installation.md。
黄金路径：从零到本地运行
前置条件是装好包管理器 uv（macOS/Linux 用官方文档里的一行安装脚本，Windows 用 PowerShell 命令，均见 docs/getting_started/installation.md）。然后执行：
mkdir my_app && cd my_app uv init uv add reflex uv run reflex initreflex init会问你要哪个模板：(0) 空白应用，(1) AI builder。第一次直接选 0，官方文档后续内容都基于它。生成后，my_app/my_app.py是应用入口，rxconfig.py是配置文件。启动开发服务器：
uv run reflex run浏览器打开http://localhost:3000就能看到默认页面。此后修改代码并保存，浏览器几秒内自动刷新，不用重启进程。
项目结构：哪些文件别碰
reflex init生成的目录不复杂，完整说明见 docs/getting_started/project-structure.md：
.venv/是 uv 建的虚拟环境，依赖和系统 Python 隔离。.web/是编译产物目录 ⚠️ 不要编辑、不要提交；每个页面会编译出对应的.js，排查编译问题时倒是可以看看。assets/放图片、字体等静态资源，组件里直接按路径引用。pyproject.toml记录依赖，uv.lock锁定解析后的版本，建议提交给团队保证一致。
日常开发你只需要碰应用 py 文件这一个地方。
初始化报错速查
| 现象 | 原因 | 处理办法 |
|---|---|---|
reflex命令找不到 | 没在虚拟环境里执行，或 uv 不在 PATH | 命令一律加uv run前缀，或先激活.venv |
| 初始化卡在选择模板 | 首次 init 需要选模板 | 选 (0) 空白应用即可 |
| Windows 报 "missing a DLL required to run bun.exe" | Bun 依赖 VC++ 运行时 | 安装 Microsoft Visual C++ 2015 运行库后重试 |
| 提示端口 3000 被占用 | 其他服务占了前端默认端口（后端默认 8000） | 找到占用进程释放，或在rxconfig.py里改为空闲端口 |
| 页面空白、无响应 | 编译或前端依赖安装失败 | 加--loglevel debug重跑看日志，检查.web/pages/下是否生成了.js |
| 改了代码不刷新 | 误改了生成目录 | 只改应用源码，.web/一律不动 |
生产部署：Caddy 反代容器化方案
要上线的话，仓库自带 4 套 Docker 示例（见 docker-example/README.md），新手最实用的是production-compose：构建时把前端静态导出，运行时只跑后端加 Caddy 反向代理，不需要 Node.js，内存占用更小。在 docker-example/production-compose/ 目录下两条命令：
DOMAIN=example.com docker compose build DOMAIN=example.com docker compose upDOMAIN填访问域名（不带协议前缀），不填则默认给 localhost 自动申请 TLS 证书，签发过程可能花几分钟。如果应用需要更高并发，追加-f compose.prod.yaml即可带起 Postgres 和 Redis、让后端多 worker 运行；只开单端口的场景可以看simple-one-port示例。
验收：三条自检确认跑通
- 执行
uv run reflex run后打开http://localhost:3000，页面显示默认欢迎内容而不是空白或 404，说明前端跑起来了。 - 改掉
my_app/my_app.py里的页面标题并保存，几秒内浏览器标题自己变化，说明热重载生效——这是 Reflex 开发体验的核心。 - 用
uv run reflex --version确认装的版本，再对照当前版本文档查 API；需要断点调试时，按 DEBUGGING.md 在 VSCode 里以模块方式启动，或者加CI=1做无头运行验证。
三条都通过，你的第一个纯 Python Web 应用就算真正跑通了，接下来从改页面标题开始往真实功能上迭代即可。
【免费下载链接】reflex🕸️ Web apps in pure Python 🐍项目地址: https://gitcode.com/GitHub_Trending/re/reflex
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
