Gradio 6.x 版本演进深度解析：从 CHANGELOG 读懂发布节奏与核心特性全景
【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. 🌟 Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio
导读：本仓库根目录的
CHANGELOG.md是 Gradio 项目 Python 主包（对应版本号为 6.26.0）的完整发布记录档案，按版本、按 Features/Fixes 分类记录了每一次合并进主分支的 PR。本文以这份 CHANGELOG 为骨架，结合仓库源码，解读 6.0→6.26 的主线技术演进（可视化工作流gr.Workflow、Svelte 5 前端迁移、gr.cache缓存体系、gr.Server服务端模式、SSR 渲染、OAuth/MCP 与安全加固），帮助开发者快速判断每个版本"改了什么、为什么改、对应代码在哪"，以及如何在升级与贡献时高效利用这份变更档案。
仓库中的版本档案：CHANGELOG 文档定位
Gradio 仓库维护了多份随包发布的变更记录，使用时需注意区分：
| 文件 | 覆盖范围 |
|---|---|
| CHANGELOG.md（本主题文档） | 主 Python 包gradio，记录 6.26.0 一路回溯到远古版本（如 2.x、1.x），共 8242 行 |
| gradio/CHANGELOG.md | 与根目录 CHANGELOG 内容一致（两者当前起点同为 6.26.0），随源码包分发 |
| client/python/CHANGELOG.md | Python 客户端gradio_client（6.0.1 起独立升级到 2.0.0） |
| client/js/CHANGELOG.md | JS/TS 客户端@gradio/client |
从内容结构看，CHANGELOG 采用严格的"版本 →### Features/### Fixes"两级目录组织，每个条目包含 PR 编号、commit 哈希、一句功能描述与贡献者致谢。它既是给使用者的升级手册，也是判断功能成熟度（例如某功能从"引入"到"修 bug"再到"补测试"）的时间线证据。仓库中的 scripts/format_release_notes.py 表明这类发布说明由脚本格式化生成，因此格式高度统一，适合被工具解析。
版本编号体系与当前状态
当前仓库主包版本为6.26.0（可在 gradio/package.json 中确认，pyproject.toml 通过 hatch 从该文件提取版本号）。6.x 系列经历了三条阶段的编号：
- 6.0.0-dev.0 ~ 6.0.0-dev.5：预发布开发版本，主要完成 6.0 破坏性变更（Chatbot 移除 tuple 消息格式、Dataframe 构造参数变更、
theme/css/js/head等参数从 Blocks 移到launch()、show_api改名、原生 plot 组件清理弃用参数等）； - 6.0.0 → 6.26.0：正式发布后的小版本迭代，每个版本都带 Features 与 Fixes 两组条目；
- 再往前的5.x 及更早记录了历史功能（如 5.48 引入
gradio openaichatCLI），时间越早条目格式越松散（旧版条目没有统一 PR/commit 双链接）。
阅读 CHANGELOG 时应以 6.x 为主线，因为它集中反映了当前仓库代码的最新能力。
主线一：gr.Workflow可视化 AI 工作流（6.17 → 6.26）
6.x 后期最活跃的功能面是可视化工作流。时间线如下：
- 6.17.0（PR #13417）：引入
gr.Workflow与gr.WorkflowCanvas，通过graph、bind、edges参数把 Python 函数接入画布，并自动持久化到 graph JSON 文件； - 6.19.0（PR #13524）：子图（subgraph）通过 Gradio API 执行——每个子图暴露为命名端点并复用
/info、/call、/api，画布上提供 "View API" 面板； - 6.20.0：点端口自动创建节点、运行子图时显示下游输出、调用推理客户端前先校验模型、把 token 注入 fn 函数；
- 6.21.0：接入模型端点、改进画布创作体验、新增 html modality、本地启动
gr.Workflow时自动打开浏览器、通过 chat completions 调用视觉语言模型使image-text-to-text模型节点可用； - 6.22.0：为模型节点自动创建输入/输出节点、节点可缩放、全屏图片查看、webcam/mic 采集、把节点错误信息变为可复制，并在 View API 面板中文档化
oauth_token参数； - 6.23.0：画布增加 oauth 提示；
- 6.24.0：只内联应用自有文件、让已打开的 HTML 脱离应用源（安全边界）；
- 6.25.0：支持把 Workflow 保存到 Space 本身、修复 checkbox 可见性、转发
x-ip-token以便 zerogpu Space 向调用方计费； - 6.26.0：支持 "另存为副本"、每个查看者独立保存画布布局并支持 undo/redo。
与之对应的仓库实现位于 gradio/workflow.py（后端核心，内部使用anyio.to_thread把同步服务端函数送入线程池）、gradio/components/workflowcanvas.py（WorkflowCanvas组件，从workflow.py第 34 行的导入可确认调用关系）、gradio/workflow_api.py 以及前端 js/workflowcanvas。可运行示例见 demo/workflow/run.py（调用远程模型节点做图像描述）与其配套的 demo/workflow/workflow.json。更多参考 demo 还包括demo/workflow_vlm_chat、demo/workflow_image_generator_comparison等。
主线二：前端全面迁移 Svelte 5
6.x 的发布记录中高频出现 "Migrate X to Svelte 5" 条目，这是一次横跨整个前端组件库的大规模重构，可据此看出迁移批次顺序：
- 6.0 阶段：起步修复（reload mode、队列、事件系统等 6.0 回归）；
- 6.1–6.4：Textbox、Dropdown、Markdown、Label、JSON、Gallery、File、Video、ColorPicker、UploadButton、MultimodalTextbox、StatusTracker、Dataset、FileExplorer、Code 等批量迁移；
- 6.5–6.6：Dataframe 前的重要修复与迁移收尾；
- 6.11：Dataframe 迁移到 Svelte 5；
- 6.18：Plot、Chatbot、Tabs、TabItem 迁移；
- 6.20：Image 组件迁移。
Svelte 5 迁移带来大量事件回归修复，典型如：Slider 值为 0 时change事件不触发（6.5.1）、ColorPicker 迁移后 focus/blur/submit 失效（6.6.0）、Tabs.select()切换不触发（6.20.0）、fill_height失效（6.9.0）、Gallery 全屏按钮失效（6.6.0）、组件值变化时统一派发change事件（6.18.0）。CHANGELOG 中反复出现的 "X 迁移到 Svelte 5 → 修复 Y" 模式，提示使用者在跟随大版本升级时应重点回归自己用到的组件事件。
主线三：缓存能力gr.cache/gr.Cache
缓存是 6.x 中后期补强的基础能力：
- 6.12.0（PR #13176）：引入
@gr.cache()装饰器，以及底层基于依赖注入的gr.Cache； - 6.15.0（PR #13322）：允许
gr.cache()直接作用于中间函数（gr.cache(fn)(*args)运行时调用）。
具体参数语义可对照 gradio/caching.py 的cache（第 482 行起）与Cache类（第 535 行起）：
| 参数 | 默认值 | 含义（取自源码 docstring） |
|---|---|---|
fn | 无 | 待缓存函数；作为@gr.cache（无括号）时是被装饰函数，作为@gr.cache(...)时为 None，运行时gr.cache(fn)(...)则必须可调用 |
key | None | 接收 kwargs 字典、返回可哈希缓存键的函数，例如只按prompt缓存可传lambda kw: kw["prompt"] |
max_size | 128 | 缓存条目上限，按 LRU 淘汰；0 表示不限制 |
max_memory | None | 内存总量上限，接受"512mb"、"2gb"等字符串或整数字节 |
per_session | False | True 时每个会话获得独立缓存命名空间，会话断开即清理 |
装饰器版内部经由_get_cached_wrapper包装，缓存命中绕过 Gradio 队列；同步/异步函数与生成器均支持，生成器命中时回放已缓存的所有 yield 值。Cache类则提供get(key)/set(key, **data)/keys()/clear()手动存取，采用默认参数注入方式交给事件函数使用。仓库内配套 demo 见 demo/cache_demo/run.py、demo/cache_kv_demo/run.py、demo/cache_intermediate_demo/run.py、demo/cache_manual_demo/run.py。
主线四：gr.Server、SSR 与部署形态
- 6.10.0（PR #13117）：新增服务端模式
gr.Server（不同于gr.Blocks），用于以"服务"形态承载已有 Blocks；源码位于 gradio/server.py，类定义于第 28 行继承自App。后续 6.12.0 修复了 ZeroGPU 场景下gr.Server的处理，6.17.0 起 analytics 中把 Server 模式单列为mode="server"； - SSR（服务端渲染）：6.4.0（PR #12472）"Re-enable SSR mode"、6.10.0 修复自定义组件在 SSR 下的问题；6.22.0 改进了 Node SSR 服务失败时的报错，并在预期端口上以降级方式服务（不启用 SSR）；6.23.0 修复 SSR 应用在 Ctrl+C 时卡在 "Stopping Node.js server..." 的问题；6.26.0 修复 SSR 开启时读取历史运行只能加载输入不能加载输出的问题。SSR 依赖 Node 前端代理，可参见 gradio/node_server.py 与 js/spa/src；
- 历史运行（Run History）：6.24.0（PR #13718）新增浏览器本地运行历史记录与回载，前端实现位于 js/spa/src/RunHistory.svelte；
- 代理与部署细节：6.15.0 把流量卸载到静态 worker 并用 node 作为代理；6.21.0 保留浏览器可见的代理源与 FastAPI root path；6.9.0、6.10.0 修复 FastAPI/反向代理后挂载 Gradio 的问题（
mount_gradio_app、gradio_api路径等）。
主线五：客户端、MCP 与 OAuth
- 客户端：6.0.1 将
gradio_client升级到 2.0.0；6.0.2 修复客户端流式文件下载并保持与 5.x 服务端兼容；JS 客户端 6.20.0 恢复同源凭据使跨域嵌入可用，6.21.0 为需要gr.OAuthToken的端点新增oauth_token参数（Python 与 JS 客户端均支持，且只发给声明需要该参数的端点）；6.25.0 给客户端内部 helper 任务分配独立线程池。实现可参考 client/python/gradio_client 与 client/js/src。 - MCP：6.11.0 对非队列 MCP 工具调用绕过 HTTP 回环、直接调用
blocks.process_api()降低延迟；6.16.0 在浏览器打开 MCP 端点时展示友好落地页而非裸 JSON-RPC 错误；6.23.0 在 MCP 工具输入 schema 中输出required数组；6.0 阶段支持把 Gradio MCP 应用同时以 ChatGPT 应用形式提供服务。相关代码见 gradio/mcp.py。 - OAuth：6.18.0 将过期 OAuth 会话视为登出用户；6.24.0 等待
auth_dependency并在既有应用上构建路由时应用它；6.26.0 修复过期会话导致的 OAuth 重定向死循环。实现在 gradio/oauth.py（含OAuthProfile、OAuthToken、oauth_login/oauth_logout等）。
主线六：贯穿始终的安全加固
6.x 修复了大量安全漏洞，且 CHANGELOG 中直接注明了 CVE/GHSA 编号，是升级时最应关注的条目。代表性如下：
- SSRF：Image/Gallery 的 SVG 后处理与 Audio 流式后处理中，受用户影响的 URL 拉取统一改走
safehttpx（6.16.0，PR #13436）；/gradio_api/file=<url>由开放重定向改为 SSRF 安全的流式代理（6.20.0，PR #13596）； - 路径穿越与开放重定向：
gr.FileExplorer.preprocess用_safe_join校验选中路径、拒绝逃逸root_dir的绝对/..路径（6.16.0，PR #13437）；修复gradio.oauth._redirect_to_target中被多前导斜杠/反斜杠绕过的开放重定向（6.16.0，PR #13438，恢复对 CVE-2026-28415 的防护）；为Blocks.from_config()proxy_url 的 SSRF 防护补回归测试（GHSA-jmh7-g254-2cq9，6.15.1）；隔离/proxy=请求的 cookie jar，防止恶意上游 Space 向不同*.hf.space泄 cookie（GHSA-2mr9-9r47-px2g，6.15.0）； - 上传与请求边界：对
/component_server的 multipart 上传强制max_file_size（6.20.0）；multipart 上传头超限时返回 413 而非 500（6.25.0）；加固认证与文件重定向边界（6.22.0）；HTML 前端的<script>引入警告（6.18.0）与<style>/<link>清洗（6.21.0）。
最近 10 个版本逐版速览（6.17 → 6.26）
结合上文主线，将最新版本段的关键条目按"重点 Feature / 重点 Fix"整理如下：
| 版本 | 核心 Feature | 核心 Fix |
|---|---|---|
| 6.17.0 | 引入gr.Workflow/gr.WorkflowCanvas；Server 模式独立 analytics | 前端资源自托管以支持离线使用；mistyped 组件/参数给出可定位报错；Markdown/HTML 支持布局尺寸参数 |
| 6.18.0 | Plot/Chatbot/Tabs/TabItem 迁 Svelte 5；所有组件值变化统一派发change；i18n choices 翻译；本地 HF token 用于 Workflow | UI 冻结、plt 图关闭、客户端迭代器关闭、api_name=False事件视为私有 API 等 |
| 6.19.0 | Workflow 子图以 Gradio API 形式运行（命名端点 + View API 面板） | Dropdown 无障碍化（combobox ARIA）、gr.SelectData坐标修正、全屏按钮修复、Markdown 长文本溢出修复 |
| 6.20.0 | Gallery "Download All"；Workflow 点端口自动建节点/模型校验/token 注入 | SSRF 安全代理替代开放重定向、max_file_size强制执行、Tabs.select()、ImageEditor 空闲 CPU 优化、state.change()对.stream()触发 |
| 6.21.0 | 保留代理源与 root path；Workflow 模型端点接入、html modality、VLM 走 chat completions；oauth_token客户端支持；gradio cc尊重自定义FRONTEND_DIR | 热重载下保持进行中的事件与生成器；Windows 文件名处理；HTML<style>/<link>清洗；gr.Code无初值渲染修复 |
| 6.22.0 | Workflow 节点自动建输入/输出、节点缩放、全屏图片、webcam/mic 采集、View API 面板文档化oauth_token | Prism 全局变量发布时序修复；认证与文件重定向边界加固；SSR 失败原因报告与降级服务 |
| 6.23.0 | Workflow 画布增加 OAuth 提示；MCP schema 输出required数组 | 深色模式文本可读性；内嵌应用收缩、sidebar 重叠量重算、SSR Ctrl+C 卡死修复 |
| 6.24.0 | Workflow 只内联应用自有文件；浏览器本地运行历史；等待并应用auth_dependency | 413 代替 500；Dataframe 行数变化重读虚拟窗口 |
| 6.25.0 | Workflow 可保存到 Space；转发x-ip-token计费 | OAuth 重定向死循环（过期会话）；客户端内部任务独立线程池；SSR 下历史运行加载输出 |
| 6.26.0 | Workflow 另存为副本、画布布局按查看者保存 + undo/redo；升级存在漏洞的前端依赖 | 嵌套响应式 render 上下文；PLY/OBJ 渲染为空白画布；ChatInterface 与gr.load_chat的历史 bug；挂载应用的 CORSMiddleware 兼容；服务器状态累积停止 |
6.0 → 6.16 关键版本要点回顾
更早的 6.x 版本中，以下条目对理解 API 演进尤其重要：
- 6.0.x 系列：6.0.1 升级 gradio_client 至 2.0.0、pillow 至 12.0；6.0.2 客户端兼容 5.x 服务端并修复流式文件下载。
- 6.1.0：为
gr.Audio/gr.Video增加可更新可读取的playback_position；Button 新增link_target；恢复 6.0 中弃用的 Blocks 构造参数（theme、css等）。 - 6.2.0：为组件增加自定义按钮能力；
gr.FileExplorer增加.select()/.input()事件；放宽 pydantic 依赖。 - 6.4.0：原生 plot 增加
axis_format；重新启用 SSR。 - 6.5.0：支持 pandas 3；Gallery 支持 webcam 上传与剪贴板粘贴。
- 6.6.0：隐藏无元素表单；多项 Svelte 5 迁移后事件修复。
- 6.7.0：
gr.HTML可作为布局元素并支持服务端函数与push_to_hub；gradio skills add支持生成 Space 专属 skill；加载模型支持:fastest/:cheapest；SKILLS.md纳入仓库。 - 6.8.0：允许从
gr.HTML上传文件。 - 6.9.0：
gr.HTML可触发任意事件名；gr.HTML的js_on_load新增watch函数。 - 6.10.0：引入
gr.Server；Gradio Prediction CLI 命令；主题类增加custom_css参数；新增核心主题；后端性能剖析（trace/benchmark）能力。 - 6.11.0：Dataframe 迁移 Svelte 5；组件 pre/post 处理移入独立线程；Starlette 1.0 兼容。
- 6.12.0：引入
@gr.cache()/gr.Cache；大量组件（Slider、Layout、Chatbot、Gallery、Label、AnnotatedImage 等）补齐单元测试；开始 vendor 依赖并给 CI 加exclude-newer。 - 6.13.0：
Request.state序列化 typo 修复；批处理队列事件请求上下文丢失修复。 - 6.14.0：Model3D/Dialogue/UploadButton/ColorPicker 等单元测试；新增主题设计器 skill。
- 6.15.0：
gr.cache()支持作用于中间函数；代理 cookie jar 隔离（GHSA-2mr9-9r47-px2g）；静态 worker 卸载流量。 - 6.16.0：
GRADIO_HEARTBEAT_INTERVAL环境变量可配置会话心跳；FileExplorer 路径穿越修复、OAuth 开放重定向修复（CVE-2026-28415）、SVG SSRF 修复、Dataframe 虚拟窗口浏览器冻结修复、运行时切换语言的全面重翻译修复。
从 6.12 开始出现大量 "XXX Unit Tests"，配合test/目录下的 test_components.py、test_blocks.py 等，可以看出 6.x 中期把质量基建（单测、playwright e2e、lint/type-check CI）作为重要投入方向。
工程实践：如何高效使用这份 CHANGELOG
- 定位升级影响面：先看当前版本到目标版本之间每个版本标题下的内容，凡涉及你用到的组件（例如 Dataframe、Plot、Chatbot、gr.HTML）的条目都要逐个过；关注标题含 "Migrate … to Svelte 5" 或 "Fix … regression" 的条目。
- 按主题横切追踪：CHANGELOG 是纵向时间线，主题演进需要横切。例如追踪 Workflow，就按上文"主线一"的方式把多个版本条目串联阅读，再到 gradio/workflow.py 与 demo/workflow/run.py 中看最终形态。
- 把安全条目当升级优先级：带 CVE/GHSA 编号的条目（SSRF、路径穿越、cookie 泄漏、开放重定向）应作为升级硬性理由。
- 识别预发布与正式版：形如
6.0.0-dev.N是正式发版前的开发快照，功能与参数到正式版可能再次变化（例如 6.0.0-dev.3 变更 Dataframe 构造参数、dev.2 把theme/css/js/head移到launch()），历史 CHANGELOG 可帮你厘清参数何时被移动/重命名，避免翻阅旧教程踩坑。
结语
CHANGELOG.md是观察 Gradio 6.x 工程演进最直接的窗口：从 6.0 的大版本破坏性清理，到 6.12 起缓存与测试基建补强，再到 6.17 之后以gr.Workflow为牵引的可视化 AI 管线与持续的安全加固，每一条记录都能在仓库源码（gradio/workflow.py、gradio/caching.py、gradio/server.py、gradio/oauth.py、gradio/mcp.py）与 demo 示例中找到落点。需要说明的是：以上版本记录以当前仓库快照为准（最新记录为 6.26.0），后续版本的变更需以更新后的 CHANGELOG 文件为准。
【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. 🌟 Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
