Streamlit 开发环境搭建指南基于 uv 的依赖管理、虚拟环境与项目初始化实战【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlitStreamlit 是当前仓库Streamlit版本 1.64.0提供的 Python Web 应用框架核心目标是用最少的代码把数据脚本变成可交互的 Web 应用。本文围绕仓库内置的开发技能文档 environment-setup.md 展开系统讲解 Streamlit 项目的环境搭建、依赖管理、目录组织与运行方式新项目优先使用 uv 自动创建隔离环境始终锁定最新版 Streamlit并遵循streamlit_app.py单一入口的工程惯例。读完本文你将能够独立完成一个 Streamlit 项目的从零初始化、依赖增删、版本核对与多页应用结构规划。环境管理总原则沿用项目现有方案新项目默认 uv在动手搭建环境前先明确一个基本判断Streamlit 本身不强制任何包管理工具。文档给出的核心原则是如果项目已经使用 pip、poetry、conda 等依赖管理方案就继续沿用避免在同一项目里混入多套工具链只有从零开始新项目且本机已安装 uv 时才把 uv 作为默认选择——它速度快、可靠并且会自动创建隔离的虚拟环境。uv 未被安装时文档明确要求先询问用户是否安装 uv而不是擅自改动用户机器的全局环境。这一点与仓库中 AI 技能SKILL.mdStep 4: Check Running Apps and Offer to Run 的交互风格一致技能只负责给出建议与命令是否执行由用户确认。从仓库根目录的 uv.lock 可以看出Streamlit 官方仓库自身也使用 uv 管理依赖并提交锁文件用于保证 CI 与本地环境的可复现构建。这为uv 作为默认工具提供了项目内部的实践佐证。关键前提始终使用最新版 Streamlit文档用一个专门的CRITICAL小节强调依赖声明中必须指定最新版 streamlit。原因在于本技能库中大量功能和用法依赖较新版本旧版本会直接导致以下特性报错Material 图标语法:material/icon_name:st.pills()、st.segmented_control()等新一代选择类控件现代缓存装饰器st.cache_data/st.cache_resourcest.navigation、st.Page等多页应用导航 API。因此无论是新建项目还是在既有项目里修复问题第一步都应是检查并升级 streamlit 版本。这与仓库现状一致当前 lib/pyproject.toml 中 streamlit 的版本为1.64.0且requires-python 3.10Python 3.103.14 均被官方分类器声明支持。实践中可用如下命令核对已安装版本streamlit version uv pip show streamlit | grep Version快速开始纯虚拟环境方案uv venv对于简单应用文档推荐只创建虚拟环境、不引入完整工程文件的轻量路线uv venv source .venv/bin/activate # Windows 下为 .venv\Scripts\activate uv pip install streamlit激活后直接安装最新版 streamlit然后运行streamlit run streamlit_app.py这一命令会启动本地开发服务器默认端口 8501并在浏览器打开应用。从仓库入口源码看streamlit run的 CLI 实现位于streamlit.web.clipython -m streamlit run ...与直接调用streamlit走的是同一条主流程见 lib/streamlit/main.py因此在 IDE 配置运行目标时python -m streamlit run app.py与streamlit run app.py等价。完整项目方案uv init 与可复现构建当项目规模较大、或需要多人协作的可复现环境时文档推荐走完整的工程化流程uv init my-streamlit-app cd my-streamlit-app uv add streamlituv init会一次性生成三样东西生成物作用pyproject.toml声明项目元信息与依赖清单uv.lock锁定精确依赖版本保证构建可复现.venv/隔离的虚拟环境随项目创建随后通过uv run运行应用无需手动激活环境uv run streamlit run streamlit_app.pyuv run会自动解析pyproject.toml中的依赖并确保环境就绪这正是 cli.md 中推荐使用uv run的原因它自动管理虚拟环境、从pyproject.toml解析安装依赖、跨机器保证环境一致并且省去了手动 activate/deactivate 的步骤。运行选项仅在确有必要时设置文档的态度非常明确避免设置运行选项除非你有具体理由。唯一的示例是 CI/自动化场景streamlit run streamlit_app.py --server.headless true # 仅用于自动化/CI 环境这一建议背后有源码依据。在 lib/streamlit/config.py 中server.headless的默认值本身已具备智能判断_create_option(server.headless, type_bool) def _server_headless() - bool: If false, will attempt to open a browser window on start. Default: false unless (1) we are on a Linux box where DISPLAY is unset, or (2) we are running in the Streamlit Atom plugin. return ( env_util.IS_LINUX_OR_BSD and not os.getenv(DISPLAY) and not os.getenv(WAYLAND_DISPLAY) )也就是说在无图形界面的 Linux 服务器如 CI 环境上headless默认即为 true无需显式指定只有在需要强制抑制浏览器弹出提示时才应手动设置。这也解释了文档不要随意加选项的用意Streamlit 已针对常见场景做了合理默认。若确需在命令行覆盖配置语法遵循--section.optionvalue模式且必须放在脚本名之后例如streamlit run app.py --server.port8080 --server.runOnSavetrue其中server.runOnSave文件变更自动重跑默认 false见 config.py与client.showErrorDetails等均可通过此方式临时覆盖。更推荐的做法是持久化到.streamlit/config.toml并遵循 cli.md 记载的优先级顺序命令行参数 环境变量STREAMLIT_* 脚本级配置 项目级配置 全局配置。添加依赖两种方式对应两种项目形态依赖安装方式与项目初始化方式一一对应# 纯 venv 方案 uv pip install plotly snowflake-connector-python # 完整工程方案uv init 之后 uv add plotly snowflake-connector-pythonuv add的优势在于它会同步写入pyproject.toml并更新uv.lock让依赖变更可追溯、可复现uv pip install则只作用于当前虚拟环境适合临时验证。项目结构保持简单按需扩展文档给出的默认目录结构极其克制my-streamlit-app/ ├── .venv/ └── streamlit_app.py只有在确实需要时才逐步追加追加项适用场景app_pages/多页应用配合st.navigationst.Page.streamlit/config.toml需要自定义主题或服务端设置.streamlit/secrets.toml使用密钥/凭据必须加入.gitignorepyproject.toml使用uv init做可复现构建关于 secrets 的这条要求与 SKILL.md 的最佳实践一致凭据绝不硬编码进应用代码也绝不把.streamlit/secrets.toml提交进版本库。命名约定与主模块职责主入口文件统一命名为streamlit_app.py——这正是streamlit run无参数调用时的默认查找目标见 cli.md 的 entrypoint 规则表。主模块的职责按应用形态划分使用导航多页时streamlit_app.py充当路由器负责定义页面并驱动它们运行无导航单页时它就是承载主内容的首页。仓库内置的仪表盘模板可作为直观参照模板入口统一命名为streamlit_app.py例如 dashboard-metrics/streamlit_app.py其中st.set_page_config()、st.cache_data(ttl...)加载器、st.fragment(parallelTrue)卡片等均体现了当前版本 API 的推荐用法。pyproject.toml 完整示例与解析文档给出的可直接套用的pyproject.toml[project] name my-streamlit-app version 0.1.0 requires-python 3.11 dependencies [ streamlit, plotly5.0.0, snowflake-connector-python3.0.0, ] [tool.uv] dev-dependencies [ pytest8.0.0, ]几点实战说明streamlit不写版本下限等价于始终装最新版与文档的 CRITICAL 要求吻合若项目对稳定性敏感也可写成带下限的区间例如streamlit1.40.0requires-python应按团队实际 Python 版本设定文档示例为3.11而仓库自身支持3.10见 lib/pyproject.toml[tool.uv] dev-dependencies是 uv 的约定小节把 pytest 等开发依赖与运行时依赖分离uv sync时会按需安装。仓库内置模板的声明方式与此一脉相承例如 dashboard-metrics/pyproject.toml 中依赖streamlit、altair5.5.0、numpy1.26.0、pandas2.2.3并声明requires-python 3.10是最小可用工程文件的官方范本。版本核对与升级检查清单综合文档与仓库信息一个规范的 Streamlit 环境初始化流程可归纳为沿用既有依赖管理工具pip/poetry/conda新项目在已装 uv 时默认用 uv检查并确保streamlit为最新版本streamlit version或uv pip show streamlit核对简单应用走uv venvuv pip install streamlit正式项目走uv inituv add streamlit主文件统一命名streamlit_app.py用streamlit run或uv run streamlit run启动除非确有原因如 CI 强制 headless不为启动命令附加多余配置选项结构保持精简仅在需要多页、主题、密钥或可复现构建时逐项追加对应文件。小结本文以仓库技能文档 environment-setup.md 为骨架结合 lib/pyproject.toml、config.py、main.py 及模板工程等仓库证据完整覆盖了 Streamlit 环境搭建的决策树从沿用现有方案还是引入 uv到快速 venv 还是完整工程再到何时才该加运行选项。无论你是首次接触 Streamlit 的新手还是需要为团队固化脚手架的老手遵循最新版本 uv 隔离环境 精简结构 约定入口这套组合都能获得稳定、可复现且贴近官方推荐的开发体验。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考