作为一名 Python 兴趣者，我近期基于 Streamlit 开发了非遗文创展示网页，完成本地开发后，核心需求就是让这个应用能被任何人通过公网链接访问。对比多种部署方案后，发现Streamlit Community Cloud（Streamlit 官方免费部署平台）是新手最友好的选择 —— 无需服务器、无需复杂配置、完全免费，今天就把我踩坑后总结的「保姆级部署步骤」分享给大家。
首先给大家看一下我文件夹所有的网页相关的文件——2.py为我的streamlit web运行代码，wenchuang-env是后边部署虚拟环境时生成的文件夹，此时不需要管，其余图片为web页面中所涉及的图片，其中.txt文件为在Github中上传文件时所需准备的一个文件，这里建议大家将代码扔给ai，让ai告诉我们这个文档里是什么内容，我们手动添加，我开始使用命令生成的都为乱码，不可用
一、为什么选 Streamlit Community Cloud？
在尝试阿里云 ECS、Heroku 等方案后，我最终选择官方云的核心原因：
- 🆓 完全免费，无广告、无强制付费升级；
- 🚀 一键部署，无需手动配置环境 / 依赖 / 端口；
- 🔄 自动同步 GitHub 代码，修改后提交即可自动更新；
- 🎯 原生适配 Streamlit 所有功能（session_state、交互组件、图片加载等）；
- 📱 自动适配移动端，无需额外做响应式设计。
唯一小限制：免费版单应用同时在线约 10 人，7 天无访问会进入休眠（首次访问慢 10 秒左右，刷新即恢复），完全满足个人展示、小型项目测试的需求。
二、部署前的 3 项核心准备（避坑关键）
部署失败 80% 的原因是前期准备不到位，这三步务必做扎实：
步骤 1：规整项目文件结构
确保所有文件放在同一个根文件夹，以我的非遗文创项目为例，标准结构如下（层级不能乱）：
wenchuang_web/ # 项目根文件夹（命名随意，建议英文） ├── 2.py # Streamlit主程序文件（核心，文件名自定义） ├── requirements.txt # 依赖清单（必须有，关键文件） ├── 1.png # 项目图片资源（所有静态文件放同级） ├── 首页1.png # 其他图片/数据文件 └── 首页2.png⚠️ 核心要求：
- 代码中所有文件路径必须是相对路径（如
Image.open("1.png")），绝对不能用本地绝对路径（如C:\Users\XXX\1.png）； - 图片 / 数据文件必须和主程序同目录，避免子文件夹嵌套（新手易踩坑）。
步骤 2：生成「精简版」requirements.txt
新手最容易犯的错：直接执行pip freeze > requirements.txt，会导出本地所有 Python 包（包括 Anaconda 自带的、Windows 专属的冗余依赖），部署时大概率报错。
本人建议使用ai后，我们手动添加；
正确做法：
- 先梳理项目真正依赖的包（我的项目仅用 2 个）；
- 手动创建
requirements.txt，只保留核心依赖，且注意版本兼容性：
# requirements.txt 内容（复制即可用） streamlit==1.50.0 # 固定版本，避免自动升级出问题 Pillow>=10.0.0 # 关键：9.x版本与Python 3.14不兼容，必须≥10.0.0步骤3：本地验证（必做）：
在本地创建虚拟环境，测试依赖是否能正常运行：
第一步，先将我们的2.py在后台运行起来，使用streamlit run 2.py，本地机运行成功
在本地创建虚拟环境，测试依赖是否能正常运行：依次在powershell中执行下面语句
# 1. 创建虚拟环境（Windows系统，Mac/Linux替换为对应命令） python -m venv wenchuang-env # 2. 激活虚拟环境 .\wenchuang-env\Scripts\activate # 3. 安装依赖 pip install -r requirements.txt # 4. 运行应用，验证功能正常 streamlit run 2.py成功示例
如果浏览器能正常打开应用、图片加载无误、交互功能（如购物车）可用，说明依赖配置正确。
步骤 4：上传代码到 GitHub（核心前提）
Streamlit Community Cloud 通过 GitHub 仓库获取代码，需先完成这一步：
1. 注册 GitHub 账号（免费）
访问https://github.com/，完成账号注册（记住用户名和密码，后续登录要用）。
2. 创建 GitHub 仓库
- 点击右上角「+」→「New repository」；
- 填写仓库名称（如
wenchuang_web，建议和本地文件夹名一致）； - 勾选「Add a README file」（可选，方便管理）；
- 点击「Create repository」创建仓库。
3. 上传本地代码到 GitHub
如果不习惯命令行，推荐用「GitHub Desktop」（https://desktop.github.com/）：
- 安装后登录 GitHub 账号；
- 点击「Add repository」→「Add existing repository」，选择本地项目文件夹；
- 点击「Commit to main」（填写提交说明，如「初始化项目」）；
- 点击「Push origin」，等待代码上传完成。
✅ 验证：打开 GitHub 仓库页面，能看到所有项目文件（2.py、requirements.txt、图片），说明上传成功。如下图所示：
三、Streamlit Community Cloud 部署（10 分钟搞定）
前期准备完成后，部署步骤全程可视化，无需敲一行命令：
步骤 1：登录 Streamlit Cloud
访问官网：https://share.streamlit.io/，点击「Log in」，选择「Log in with GitHub」，授权 GitHub 账号（只需允许访问你的项目仓库即可）。
步骤 2：创建新应用
- 登录后，点击页面右上角「New app」（蓝色按钮）；
- 进入部署配置页，按以下要求填写（关键，不能错）：
配置项 填写说明 Repository 选择你上传代码的 GitHub 仓库（如：你的用户名 /wenchuang_web） Branch 默认选「main」或「master」（GitHub 仓库默认分支） Main file path 填写 Streamlit 主程序文件名（如：2.py，务必和本地文件名一致） - 可选：点击「Advanced settings」，可设置 Python 版本（建议选 3.10+，避免兼容性问题）。
如图所示部署成功
步骤 3：启动部署
- 点击页面底部「Deploy」按钮，开始部署；
- 部署过程会显示日志（约 1-3 分钟），主要看 3 个关键阶段：
- 🐙 Cloning repository：克隆 GitHub 仓库（成功则显示「Cloned repository!」）；
- 📦 Processing dependencies：安装 requirements.txt 中的依赖（重点看 Pillow 和 Streamlit 是否安装成功）；
- 🚀 Starting up：启动应用（无报错则部署完成）。
如图所示部署成功，这样就可以分享链接了
步骤 4：获取公网访问链接
部署成功后，页面会自动跳转到你的应用页面，浏览器地址栏就是公网访问链接（点击shar，copy link），可直接分享给任何人访问。
✅ 验证：复制链接到手机 / 另一台电脑，能正常打开应用，说明部署成功。
四、部署常见踩坑及解决方案（亲测有效）
表格
| 问题现象 | 核心原因 | 解决方案 |
|---|---|---|
部署日志报错KeyError: '__version__' | Pillow 9.x 版本与 Python 3.14 不兼容 | 将 requirements.txt 中 Pillow 版本改为>=10.0.0，提交到 GitHub 后重启应用 |
| 应用能打开但图片无法显示 | 图片未上传到 GitHub / 路径错误 | 确认图片在 GitHub 仓库中，代码中用相对路径（如"1.png"），而非绝对路径 |
| 依赖安装超时 / 失败 | 依赖冗余 / 网络问题 | 精简 requirements.txt（只保留必要包），或在 Advanced settings 中设置国内 pip 源 |
| 应用休眠后访问慢 | 免费版机制 | 无需处理，首次访问等待 10 秒左右，后续自动恢复 |
五、部署后关键操作
1. 更新应用（修改代码后）
- 本地修改代码→保存；
- 用 GitHub Desktop 提交修改→Push 到 GitHub 仓库；
- Streamlit Cloud 会自动检测更新并重新部署（约 1 分钟），无需手动操作。
2. 管理应用
- 登录 Streamlit Cloud，在「Apps」页面能看到所有部署的应用；
- 点击应用右侧「⋮」，可选择「Restart app」（重启应用）、「Settings」（修改配置）、「Delete app」（删除应用）。
3. 常见疑问解答
Q：退出本地虚拟环境（deactivate）/ 关闭电脑，公网链接还能用吗？
A：完全可以！本地环境和云端应用是两个独立的系统，云端应用运行在 Streamlit 的服务器上，本地操作（如 deactivate、关闭终端）不会影响公网访问。
Q：免费版有流量限制吗？
A：单应用同时在线约 10 人，日常展示完全够用；如果需要更高并发，可升级到付费版（每月 $9 起）。
Q：能绑定自定义域名吗？
A：免费版不支持，付费版可绑定自己的域名（如https://yourname.com）。
六、总结
Streamlit Community Cloud 是新手部署 Streamlit 应用的「最优解」，核心流程可总结为：
- 规整文件结构 + 精简依赖（避坑核心）；
- 上传代码到 GitHub；
- 登录 Streamlit Cloud 一键部署；
- 复制公网链接即可分享。
整个过程无需懂服务器、无需敲复杂命令，只要抓住「精简依赖、规范路径」两个核心，10 分钟就能从本地代码变成全网可访问的应用。希望这篇教程能帮到你，快去部署自己的 Streamlit 应用吧！
