Reflex 使用指南用纯 Python 构建全栈 Web 应用并快速部署【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflexReflex 是一个让你用纯 Python 编写全栈 Web 应用的库前端 UI、后端逻辑乃至数据库访问全部在 Python 中完成无需学习 JavaScript也无需单独维护前后端两套工程。本指南以仓库根目录 README.md 为核心带你走通安装 → 初始化项目 → 编写交互页面 → 理解底层运行机制的完整链路并在关键环节结合仓库源码如 reflex/state.py、reflex/app.py、reflex/reflex.py进行验证帮助你写出可运行、可部署、可扩展的 Reflex 应用。Reflex 是什么根据 README.md 的定位Reflex 的核心能力是Build full-stack web apps in pure Python.用纯 Python 构建全栈 Web 应用。它强调两个关键特性Pure Python纯 Python应用的前端与后端全部用 Python 编写不必再学习 JavaScript。Reflex 会把你在 Python 中声明式定义的组件编译为运行在浏览器里的前端代码而后端逻辑保持 Python 原样运行在服务器上。Full Flexibility完全灵活Reflex 上手门槛低几分钟就能跑起第一个应用同时它也具备支撑复杂应用的能力可以从小型数据应用扩展到大型多页面网站。官方文档甚至宣称 Reflex 官网本身就是用 Reflex 构建并部署的见 docs/getting_started/introduction.md。在 pyproject.toml 中项目自述为 Web apps in pure Python.要求 Python 版本3.10,4.0并随包一起分发了一批按功能拆分的组件包如reflex-components-core、reflex-components-radix、reflex-components-recharts等这也是开箱即用、组件丰富这一体验的底层来源。环境准备与安装强烈建议使用虚拟环境以确保reflex命令出现在 PATH 中。README 与 docs/getting_started/installation.md 均推荐使用 uv 作为默认包管理工具venv、conda、poetry也是可选方案。在 macOS/Linux 上先安装 uvcurl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启终端或执行source ~/.bashrczsh 用户执行source ~/.zshrc。Windows 用户推荐使用 WSL并可直接用 PowerShell 安装 uvpowershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex需要注意Python 3.10 的支持在 reflex/init.py 中已被标记为 deprecated and will be removed in a future release建议直接使用 Python 3.11 或更高版本。创建你的第一个 Reflex 应用README 给出了基于 uv 的最小启动流程共四步mkdir my_app_name cd my_app_name uv init uv add reflex uv run reflex init uv run reflex run逐步拆解如下mkdir my_app_name cd my_app_name创建并进入应用目录uv init初始化一个 Python 项目生成pyproject.toml等基础文件uv add reflex安装 Reflex并把依赖写入pyproject.tomluv run reflex init初始化 Reflex 项目骨架——它会创建应用目录、assets静态资源目录、rxconfig.py配置文件并生成默认应用文件如my_app_name/my_app_name.pyuv run reflex run启动开发服务器。启动成功后访问 http://localhost:3000 即可看到你的应用。uv run reflex run默认同时拉起前端:3000与后端:8000两个服务排查问题时可用uv run reflex run --loglevel debug提升日志详细程度见 docs/getting_started/installation.md。reflex init在交互提示中会询问使用哪种模板Initializing the web directory. Get started with a template: (0) A blank Reflex app. (1) Try our AI builder. Which template would you like to use? (0):首次上手建议选择(0) A blank Reflex app。初始化后的项目结构初始化完成后的典型目录结构详见 docs/getting_started/project-structure.mdhello ├── .venv # uv 创建的虚拟环境隔离项目依赖 ├── .web # 前端编译产物目录由 Reflex 自动生成无需手动编辑 ├── assets # 存放图片、字体等公开静态资源 ├── hello │ ├── __init__.py │ └── hello.py # 你的应用主文件默认应用写在这里 ├── .gitignore ├── .python-version ├── pyproject.toml # Python 项目元数据与依赖声明 ├── rxconfig.py # Reflex 应用配置入口 └── uv.lock # 锁定完整依赖版本保证可复现安装几个要点.web/是编译后的 JavaScript 存放位置每个 Reflex 页面会对应编译出.web/pages下的一个.js文件调试时可以参考但不要手工修改前端依赖的锁文件存放在项目根目录的reflex.lock/bun.lock独立目录可避免与用户自管的 bun 项目冲突rxconfig.py默认形如import reflex as rx config rx.Config( app_namehello, )修改my_app_name/my_app_name.py后保存Reflex 会热更新fast refresh刷新即见效果这是开发阶段的核心体验。示例应用用纯 Python 构建图片生成 AppREADME 提供了一个完整的可运行示例——一个调用图像模型生成图片的应用。它只用了三个核心概念State状态、event handlers事件处理器与components组件。import reflex as rx import openai client openai.AsyncOpenAI() class State(rx.State): prompt: str image_url: str processing: bool False rx.event def set_prompt(self, value: str): self.prompt value rx.event async def generate(self): self.processing True yield response await client.images.generate( modelgpt-image-1.5, promptself.prompt, ) self.image_url fdata:image/png;base64,{response.data[0].b64_json} self.processing False def index(): return rx.vstack( rx.heading(Image Generator), rx.input(placeholderEnter a prompt..., on_changeState.set_prompt), rx.button(Generate, on_clickState.generate, loadingState.processing), rx.image(srcState.image_url), ) app rx.App() app.add_page(index, titleReflex:Image Generation)Reflex 图片生成示例应用预览下面逐块拆解这段代码背后的机制。1. State应用的数据中枢class State(rx.State): prompt: str image_url: str processing: bool FalseState保存应用的可变数据类中声明的带类型注解的字段被称为vars状态变量。前端组件引用这些 var 后会在状态变化时自动响应式地重新渲染详见 docs/getting_started/basics.md 与 docs/vars/base_vars.md。在源码层面reflex/state.py 定义了完整的State体系状态通过 delta增量机制同步到前端并提供了类型检查、序列化、代理对象MutableProxy等能力过大的状态还会触发StateTooLargeError之类的一致性保护。从实现看Reflex 会把 state var 编译为前端可引用的变量并在事件处理后仅推送发生变化的部分这是它前端轻量同步的底层支撑。2. Event handlers唯一允许修改状态的地方rx.event def set_prompt(self, value: str): self.prompt value rx.event async def generate(self): self.processing True yield response await client.images.generate(...) self.image_url ... self.processing False事件处理器event handlers是修改 State 的唯一途径用户点击、输入等动作即事件触发它们。要点rx.event装饰器自 Reflex 0.6.5 起被强烈推荐它能让事件处理器获得正确的静态类型检查参数数量与类型不匹配会在编译期报错事件处理器可以是async的也可以使用yield推送中间状态。上面的generate先yield一次把processing True推送到前端按钮随即进入 loading 状态再异步等待模型返回结果最后更新image_url并结束处理。这正是 docs/getting_started/installation.md 中提到的 Event handlers may beasyncand mayyieldto push intermediate UI updates 约定事件处理器运行在后端Python 进程中因此可以自由使用任意 Python 库与任意代码——这里直接调用了openai的异步客户端。从源码看reflex/event.py 是reflex_base.event的重导出模块事件、事件链EventChain、EventHandler、call_script等基础设施都在此命名空间下注册并最终通过 reflex/init.py 以rx.event等名称暴露给用户。3. Components声明式 UIdef index(): return rx.vstack( rx.heading(Image Generator), rx.input(placeholderEnter a prompt..., on_changeState.set_prompt), rx.button(Generate, on_clickState.generate, loadingState.processing), rx.image(srcState.image_url), )UI 由组件构建子组件通过位置参数嵌套属性通过关键字参数props传入组件引用 state var如rx.image(srcState.image_url)时具备响应式能力——状态一变UI 自动更新事件触发器如on_change、on_click把 UI 动作接到事件处理器上CSS 属性以 snake_case 形式作为 prop 传入如font_size、border_radius并支持 Tailwind 与自定义样式。Reflex 内置了 50 组件覆盖表单、布局、数据展示、图表等场景当内置组件不够用时还可以包装任意 React 组件详见 docs/components/conditional_rendering.md、docs/components/props.md、docs/wrapping-react/overview.md。从 reflex/init.py 可以看到rx.*命名空间采用懒加载lazy_loader方式注册了大量组件rx.button、rx.input、rx.image、rx.vstack等来自reflex_components_core与 Radix 主题映射rx.data_table来自 gridjsrx.plotly来自 plotly 包rx.code_block来自 code 组件包。这意味着组件丰富不是堆在一个大文件里而是按功能拆分成独立发行包、按需导入——既降低了导入开销也方便单独演进。4. App 与页面注册app rx.App() app.add_page(index, titleReflex:Image Generation)rx.App是应用的入口对象add_page把页面函数注册到指定路由。在源码 reflex/app.py 中add_page的签名支持这些常用参数component页面组件或返回组件的可调用对象route页面路由若组件是函数则默认以函数名作为路由title/description页面标题与描述SEO 元信息image页面展示图片on_load页面每次加载时触发的事件处理器meta页面元数据context供页面使用的自定义上下文。创建多个页面并链接导航的完整路由机制可参考 docs/pages/overview.md。事件响应链路一次点击发生了什么对于rx.button(Generate, on_clickState.generate)这样的交互docs/getting_started/introduction.md 给出了完整链路用户点击 Generate 按钮触发on_click事件State.generate在服务器端执行状态被更新processing、image_url等UI 依据新状态自动重渲染。这条链路也解释了 Reflex 的编译期/运行期划分编译期页面组件被编译成在浏览器运行的 JavaScript运行期State 与事件处理器以纯 Python 形式运行在服务器端。因此组件树中对 state var 使用原生if/for/len()是不允许的编译期无法获知运行时值必须改用rx.cond、rx.foreach与 var 运算符——这是新手最常见的错误详见 docs/getting_started/basics.md 与 docs/components/conditional_rendering.md。命令行工具与部署reflex命令本身在 pyproject.toml 中注册为reflex reflex.reflex:cli其实现位于 reflex/reflex.pycli是一个基于 click 的命令组自带版本号reflex --version并管理init、run、export、deploy等子命令。其中与云端部署相关的命令依赖独立的reflex-hosting-cli包pyproject.toml中已将其列为默认依赖若缺失会给出安装提示。本地自托管部署、Docker 镜像与反向代理等方案可参考本仓库的 docker-example/ 目录——它提供了simple-one-port单端口、production-one-port生产单端口、production-composeCaddy Compose等多种现成模板配合 docs/hosting/self-hosting.md 即可完成生产级部署。Reflex Cloud 的一键部署流程见 docs/hosting/deploy-quick-start.md。小结与下一步本指南从 README.md 出发完成了环境准备与 uv 安装通过uv init→uv add reflex→uv run reflex init→uv run reflex run创建并运行第一个应用借助图片生成示例掌握 State / 事件处理器 / 组件 / 页面注册四大核心概念结合源码理解事件链路、编译期与运行期边界以及rx.*组件的懒加载组织方式。继续深入的方向状态体系状态继承、计算属性rx.var、组件级状态与共享状态见 docs/state/overview.md 与 docs/vars/computed_vars.md路由与多页面动态路由、页面导航见 docs/pages/overview.md 与 docs/pages/dynamic_routing.md底层原理前端如何编译、状态如何同步见 docs/advanced_onboarding/how-reflex-works.md实战教程仪表盘数据应用见 docs/getting_started/dashboard_tutorial.md流式 AI 对话应用见 docs/getting_started/chatapp_tutorial.md。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考