Reflex CLI 完全指南用reflex命令完成应用的初始化、运行、导出与部署【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflexReflex 的官方命令行工具CLI是开发者操作 Reflex 应用的核心入口覆盖了从创建项目、开发调试、数据库迁移到生产构建与云端部署的完整生命周期。本指南以官方 CLI 参考文档为主线结合当前仓库中reflex/reflex.py、reflex/utils/export.py、reflex/utils/rename.py等源码实现系统讲解每个子命令的用法、参数含义与底层执行流程帮助你熟练驾驭reflex init、reflex run、reflex export、reflex db等高频命令并理解它们背后实际发生了什么。CLI 概览一个命令入口多个功能子命令reflex命令行接口是一个用于创建和管理 Reflex 应用的工具。运行reflex --help可以查看所有可用命令$ reflex --help Usage: reflex [OPTIONS] COMMAND [ARGS]... Reflex CLI to create, run, and deploy apps. Options: --version Show the version and exit. --help Show this message and exit. Commands: cloud The Hosting CLI. component CLI for creating custom components. db Subcommands for managing the database schema. deploy Deploy the app to the Reflex hosting service. export Export the app to a zip file. init Initialize a new Reflex app in the current directory. login Authenticate with experimental Reflex hosting service. logout Log out of access to Reflex hosting service. rename Rename the app in the current directory. run Run the app in the current directory. script Subcommands for running helper scripts.从源码看CLI 入口定义在 reflex/reflex.py 中它基于 Click 框架以click.group方式组织并通过click.version_option暴露--version选项输出当前 Reflex 版本号。值得注意的两个全局细节共享日志选项reflex init、run、export等命令都通过log_options装饰器定义于 reflex/utils/cli_options.py注入统一的--loglevel与--json选项。其中--loglevel支持debug / default / info / warning / error / critical--json则让日志以机器可读的 JSON 记录输出方便集成到日志采集系统。可选依赖命令cloud、deploy依赖独立的reflex-hosting-cli包。当该包未安装时CLI 会注册一个“占位命令”运行时报错并提示pip install reflex-hosting-cli而不是直接报命令不存在。reflex init初始化一个新 Reflex 应用reflex init在当前目录创建一个新的 Reflex 应用。如果目录下已存在rxconfig.py它会使用最新模板重新初始化应用。$ reflex init --help Usage: reflex init [OPTIONS] Initialize a new Reflex app in the current directory. Options: --name APP_NAME The name of the app to initialize. --template [demo|sidebar|blank] The template to initialize the app with. --loglevel [debug|info|warning|error|critical] The log level to use. [default: LogLevel.INFO] --help Show this message and exit.参数说明参数说明--name APP_NAME指定应用名称。不指定时源码中会通过prerequisites.validate_app_name校验并生成合法名称仅允许字母、数字、下划线、连字符等合法 Python 标识符字符。--template初始化所用的模板可选demo带示例页面、sidebar侧边栏布局、blank空白模板也是默认模板。模板常量定义于 packages/reflex-base/src/reflex_base/constants/base.py 的Templates.DEFAULT blank。--loglevel日志级别默认info。源码视角init 实际做了什么查看 reflex/reflex.py 中_init的实现reflex init的执行流程依次是输出系统信息exec.output_system_info()显示 Python 版本、操作系统、CPU 等环境概要校验应用名称prerequisites.validate_app_name不合法直接终止检查最新包版本check_latest_package_version提醒 Reflex 是否有新版本初始化前端依赖initialize_frontend_dependencies为后续编译准备 Node/Bun 等运行时按模板初始化应用目录templates.initialize_app——将模板文件复制到当前目录并把模板目录/文件重命名为应用名同时把模板源码里的from template导入替换为from app_name见 reflex/utils/templates.py写入.gitignorefrontend_skeleton.initialize_gitignore默认生成AGENTS.mdinit命令还带有--agents/--no-agents选项默认开启用于为 AI 编码助手生成项目指引文件处理依赖声明若项目没有pyproject.toml会生成requirements.txt并提示手动加入对应版本的reflex依赖随后给出下一步运行命令的提示如uv run reflex run。因此reflex init不只是拷贝几个文件它同时完成了一整套环境自检、模板装配与工程化配置。初次使用 Reflex 前请先参考 安装指南 完成 Python 环境与 Reflex 的安装。reflex run在开发与生产模式下运行应用reflex run在当前目录运行 Reflex 应用。默认以开发模式运行应用会监听代码变更并自动热重载你也可以通过参数切换到生产模式构建优化后的产物。$ reflex run --help Usage: reflex run [OPTIONS] Run the app in the current directory. Options: --env [dev|prod] The environment to run the app in. [default: Env.DEV] --frontend-only Execute only frontend. --backend-only Execute only backend. --frontend-port TEXT Specify a different frontend port. [default: 3000] --backend-port TEXT Specify a different backend port. [default: 8000] --backend-host TEXT Specify the backend host. [default: 0.0.0.0] --loglevel [debug|info|warning|error|critical] The log level to use. [default: LogLevel.INFO] --help Show this message and exit.参数说明参数说明--env [dev\|prod]运行环境默认dev。注意在 packages/reflex-base/src/reflex_base/constants/base.py 中Env枚举实际包含三个值dev / preview / prod。其中preview是介于开发与生产之间的模式像 dev 一样热重载但不再启动 Vite 开发服务器而是把刚构建的、未压缩的前端产物挂载到后端通过--env preview即可启用。--frontend-only/--backend-only只运行前端或只运行后端对应RunningMode.FRONTEND_ONLY / BACKEND_ONLY二者不可同时使用。在只运行后端时不能指定--frontend-port反之亦然。--frontend-port前端端口默认3000。--backend-port后端端口默认8000。--backend-host后端监听主机默认0.0.0.0。--loglevel日志级别默认info。源码视角run 的执行路径run命令的完整逻辑在 reflex/reflex.py 的_run系列函数中几个关键行为值得留意环境模式决定行为dev模式下前后端各占一个端口前端跑 Vite 开发服务器并热重载preview/prod模式下前后端必须使用同一个端口源码中明确校验若两个端口被显式指定且不相等会直接报错退出。单端口生产模式reflex run --env prod --single-port可将前后端合并监听同一端口--single-port仅在生产环境可用。这也是仓库中 docker-example/production-one-port 等示例的部署形态。端口自动递增dev 模式下如果默认端口被占用processes.handle_port会自动寻找下一个可用端口并提示无需手动改配置。端口参数会持久化通过--frontend-port等传入的端口会被写入配置并持久化config._set_persistent下次运行继续生效。编译前置检查运行前会调用_compile_app编译应用并通过prerequisites.assert_in_reflex_dir确保当前目录是合法的 Reflex 项目若检测到项目需要重新初始化needs_reinit会自动先执行reflex init。后端服务器可选后端既可通过 uvicorn 运行也支持 Granian源码exec.should_use_granian会根据配置决定生产模式默认启用多 worker。运行模式速查reflex run # 开发模式前后端全栈3000/8000 reflex run --env prod # 生产模式单端口 reflex run --env preview # 预览模式真实构建产物 后端热重载 reflex run --frontend-only # 只跑前端 reflex run --backend-only # 只跑后端 reflex run --env prod --single-port # 生产模式单端口适合自托管反向代理reflex export导出前端与后端产物reflex export可以将应用的前端与后端分别导出为 zip 文件。前端是编译后的 Next.js 应用可以部署到 GitHub Pages、Vercel 等静态托管平台但它只是静态构建产物后端需要单独部署。完整的自托管方案请参考 自托管指南。$ reflex export --help Usage: reflex export [OPTIONS] Export the app to a zip file. Options: --zip / --no-zip Whether to zip the backend and frontend exports. [default: zip] --frontend-only Export only frontend. --backend-only Export only backend. --zip-dest-dir TEXT The directory to export the zip files to. [default: current directory] --exclude-from-backend PATH Files or directories to exclude from the backend zip. Can be used multiple times. --ssr / --no-ssr Whether to enable server side rendering for the frontend. [default: ssr] --env [dev|prod] The environment to export the app in. [default: prod] --loglevel [debug|info|warning|error|critical] The log level to use. --help Show this message and exit.参数说明参数说明--zip / --no-zip是否把产物打包成 zip默认打包。--frontend-only/--backend-only只导出前端或只导出后端默认两者都导出。--zip-dest-dirzip 文件的输出目录默认当前目录。--exclude-from-backend从后端 zip 中排除的文件或目录可多次指定例如排除数据目录或node_modules。--ssr / --no-ssr是否开启前端服务端渲染SSR默认开启。--env [dev\|prod]导出环境默认prod。源码视角导出流程reflex/utils/export.py 中的export函数揭示了完整流水线各阶段耗时会被记录并作为遥测数据上报编译应用prerequisites.get_compiled_app(prerender_routes...)确保应用模块可导入且app.compile()已执行搭建前端build.setup_frontend(Path.cwd())准备.web目录并安装前端依赖构建build.build()执行生产构建打包build.zip_app(...)按需分别打包前后端支持通过include_db_file决定是否包含 SQLite 数据库文件对应 CLI 中的--upload-db-file隐藏选项、通过backend_excluded_dirs排除指定路径。另外导出命令还支持通过环境变量控制只导出某一部分如REFLEX_FRONTEND_ONLY便于在 CI 流水线中按需使用。导出后的后端部署与云端部署可参考 部署快速上手 与 GitHub Actions 部署。reflex rename重命名应用reflex rename用于重命名 Reflex 应用它会同步更新配置文件中的应用名以及应用目录、模块导入等。$ reflex rename --help Usage: reflex rename [OPTIONS] NEW_NAME Rename the app in the current directory. Options: --loglevel [debug|default|info|warning|error|critical] The log level to use. --help Show this message and exit.从 reflex/utils/rename.py 的实现看重命名是全局替换而非简单改名先校验新名称合法性并确认当前目录存在rxconfig.py通过process_directory遍历项目内所有.py与.md文件默认排除.web目录与assets目录把from old_name.xxx、import old_name等导入语句替换为新名称同步更新rxconfig.py中的app_name...支持关键字参数与rx.Config(...)位置参数两种写法最后沿目录树向上重命名应用目录与模块文件rename_path_up_tree直到到达包含rxconfig.py的项目根目录为止。因此即使你在代码中多处引用了旧模块名一条reflex rename 新名称也能保持项目一致可用。reflex db数据库 Schema 管理reflex db提供数据库 schema 管理子命令源码见 reflex/reflex.py 中的db_cli组子命令作用reflex db init初始化数据库创建 schema 与迁移配置alembic。若db_url未配置或已初始化会给出明确提示。reflex db makemigrations根据模型自动生成 alembic 迁移脚本支持--message指定可读标识若目标数据库落后会提示先执行 migrate。reflex db migrate应用迁移脚本创建或更新数据库 schema。reflex db status检查数据库 schema 状态按时间顺序输出迁移历史base为起点并标出当前版本位置。这些命令面向 数据库配置 中介绍的db_url配置项。若尚未配置db_urlreflex db init会直接提示db_url is not configured, cannot initialize。reflex component自定义组件脚手架reflex component是用于创建自定义组件的 CLI实现于 reflex/custom_components/custom_components.py包含四个子命令reflex component init [--library-name NAME] [--install/--no-install]在当前目录初始化一个自定义组件项目。它会基于目录名自动推导出库名kebab-case、组件类名CamelCase、包名reflex-library-name、模块名snake_case并生成pyproject.toml、README.md、组件源码模板继承rx.Component内含library、tag、props、事件触发器的注释指引以及一个用于测试的 demo 应用。默认还会以可编辑模式-e安装该本地包。reflex component build在项目根目录执行构建会先生成.pyi类型桩文件再调用python -m build .。reflex component install以可编辑模式安装当前目录的组件包。reflex component share交互式收集组件信息包名、演示 URL、预览图登录 Reflex 后端服务后提交到组件 Gallery。更详细的封装方法可参考 wrapping-react 文档。reflex cloud / deploy / login / logout托管服务相关命令reflex cloud进入 Reflex Cloud 托管服务的子命令集用于管理应用、项目、密钥secrets等。reflex deploy把应用部署到 Reflex 托管服务。reflex login/reflex logout登录/登出 Reflex 托管服务。这些命令依赖独立的reflex-hosting-cli包。从 reflex/reflex.py 源码可以看到当包未安装时CLI 仍会注册这些命令作为占位符执行时提示需要安装reflex-hosting-clipip install reflex-hosting-cli这样用户得到的不是令人困惑的未知命令而是明确的安装指引。部署流程细节可参考 部署快速上手。reflex script 与 reflex compilereflex script提供运行辅助脚本的子命令组。在当前仓库的源码中script_cli命令组已定义并注册reflex/reflex.py用于承载 Reflex 开发相关的辅助脚本入口。reflex compile单独编译当前目录的应用--dry只做校验不落盘--rich/--no-rich控制进度条显示。reflex run内部实际上也会先执行编译这一命令适合在 CI 中做编译校验。常见问题与使用建议版本查看reflex --version输出当前版本每次init/run都会后台检查最新包版本并提示升级。端口冲突开发模式会自动递增寻找可用端口生产/预览模式强制前后端同端口如遇占用可显式指定--frontend-port与--backend-port为同一端口。日志排查所有主要命令都支持--loglevel debug查看详细日志--json可输出结构化日志便于集成。自托管部署reflex export产出前后端 zip 后可结合 自托管指南 与仓库中的 docker-example 示例含生产单端口、Caddy 反向代理等形态搭建自己的部署环境。结语Reflex CLI 将纯 Python 开发 Web 应用的完整工作流收敛到一条命令之上reflex init起步、reflex run开发调试、reflex db管理数据层、reflex export产出可部署产物再通过reflex cloud/reflex deploy或自托管方案上线。理解每个命令背后的源码执行路径能帮助你在遇到端口、依赖、模板或数据库问题时快速定位原因把命令行工具用得更顺、更稳。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考