Werkzeug 版本变更日志深度解读:从 3.2.0 到 0.1 的关键演进与源码印证

原创2026-10-05 21:41:072,170 阅读
文章标签:后端Web框架

Werkzeug 版本变更日志深度解读:从 3.2.0 到 0.1 的关键演进与源码印证

本文以仓库根目录的 CHANGES.rst(共 2935 行,覆盖 Werkzeug 从 0.1 到 3.2.0 的完整变更记录)为骨架,系统梳理各版本的核心变化,并结合 src/werkzeug 源码与 pyproject.toml 中的实际实现逐一印证。读完本文,你将掌握 Werkzeug 近几个大版本的 API 弃用与移除清单、行为变更(如 redirect 默认状态码、Cache-Control 属性语义)、安全修复脉络,以及这些变更在源码中的落点,从而在升级或使用 Werkzeug 时做出正确的迁移决策。

一、版本脉络一览

Werkzeug 自 2007 年发布 0.1 起,一直保持着"每年一到两个大版本 + 多个补丁版本"的节奏。以下时间线可以帮助你快速定位自己的版本处于哪个阶段:

大版本 发布日期 Python 支持下限 关键主题
3.2.0(开发中) 未发布 Python 3.10 大规模去重弃用 API、结构化 Header 类、redirect 默认 303、SHA3-256
3.1.x 2024-11 ~ 2026-04 Python 3.9 安全修复(safe_join、multipart DoS)、性能优化、Cache-Control 语义调整
3.0.x 2023-09 ~ 2024-10 Python 3.8 scrypt 默认哈希、multipart 加固
2.3.x 2023-02 ~ 2023-11 Python 3.8 Authorization/Cookie 重构、werkzeug.urls 弃用
2.2.x 2022-07 ~ 2023-02 Python 3.7 状态机路由器、multipart 部件上限
2.1.x 2022-03 ~ 2022-04 Python 3.7 开发服务器 HTTP/1.1 化
2.0.x 2021-05 ~ 2022-02 Python 3.6 彻底告别 Python 2、sans-IO 重构
1.0.x 2020-02 ~ 2020-03 Python 3.5 模块化导入、CSP 支持
0.x 2007-12 ~ 2020-01 Python 2.4+ 从零到 WSGI 库的完整演进

当前仓库的 pyproject.toml 中 version = "3.2.0.dev",requires-python = ">=3.10",依赖 markupsafe>=3.0.3,与 CHANGES.rst 中 3.2.0 一节"放弃 Python 3.9、最低 MarkupSafe 3.0.3、最低 Watchdog 6.0"的记录完全对应。

二、3.2.0:一次大规模"清理"型大版本

3.2.0 是当前开发中的版本,其变更条目在 CHANGES.rst 中占据最长篇幅。它的主旋律是:移除历史遗留、强化类型标注、收敛 API 表面。

2.1 平台与依赖门槛

  • 放弃对 Python 3.9 的支持(:pr:3098),与 pyproject.toml的requires-python = ">=3.10"` 一致。
  • 移除先前已弃用的代码(:pr:3099`)。
  • MarkupSafe 最低版本提升到 3.0.3。
  • Watchdog(reloader 可选依赖)最低版本提升到 6.0,对应 pyproject.toml 中 watchdog = ["watchdog>=6"] 的可选依赖声明。

2.2 数据结构与混合类(Mixin)的弃用:用类型标注替代继承

3.2.0 明确了一个方向:"Werkzeug 内部未再使用的数据结构应被弃用,可变性交给类型标注来表达"。被弃用的包括:

  • ImmutableList / ImmutableListMixin:Accept 改为直接继承 Sequence,类型上改用 tuple、Sequence、MutableSequence。
  • ImmutableDict / ImmutableDictMixin:改用 Mapping / MutableMapping 做类型标注。
  • UpdateDictMixin:改用 CallbackDict。
  • TypeConversionDict / ImmutableTypeConversionDict:类型转换的 get 仍保留在 MultiDict / ImmutableMultiDict 上。
  • OrderedMultiDict / ImmutableOrderedMultiDict 直接移除——因为底层 MultiDict 本就基于 Python dict,天然保序。

同时,Request.parameter_storage_class、dict_storage_class、list_storage_class 以及 parse_cookie、parse_form_data、FormDataParser 的 cls 参数均被弃用(:pr:3169)。从今往后,Request.form、files、args、cookies恒为ImmutableMultiDict,Request.access_route恒为Sequence。这与文档的说明一致:过去这些类允许覆盖以支持有序数据结构,但 Python 的 dict` 现已保证插入顺序,覆盖机制不再必要。

2.3 结构化 Header 类全面接管:from_header / to_header

3.2.0 引入了一个重要 API 格局:所有结构化 header 类都提供 from_header 类方法与 to_header 实例方法,而 werkzeug.http 中对应的解析函数被弃用:

  • dump_csp_header、parse_accept_header、parse_cache_control_header、parse_content_range_header、parse_csp_header、parse_etags、parse_if_range_header、parse_range_header、parse_set_header(:pr:3116`)。

源码可以印证这一格局已经落地。在 src/werkzeug/datastructures 下:

CHANGES.rst 给出的理由值得留意:这一改造"改善了静态类型,并减少循环导入"——把"解析字符串"与"序列化字符串"的能力收拢到数据类型类本身,取代散落在 werkzeug.http 中的过程式函数。

2.4 请求/响应行为变更

  • redirect 默认状态码从 302 改为 303(:pr:3092)。源码 <a href="https://link.gitcode.com/i/5a09207e558f6e71b3476bbeae33657b" target="_blank">src/werkzeug/utils.py</a> 中 def redirect(location: str, code: int = 303, ...)` 直接体现了这一变更;其文档字符串还解释了 303/307/308 各自的语义:303 恒转为 GET,307/308 保留原方法,并指出 301/302 在客户端实现中不一致(常把 POST 变 GET 而保留其他方法),因此建议优先使用 303/307/308。此变更"对前端库(如 HTMX)也是正确的"。
  • 测试客户端在重定向切到 GET 时清除更多请求体信息;只有请求方法是 POST 时,301/302 才转为 GET;不再把 305 当作重定向(它已不在 HTTP 规范中)。
  • Request.host、get_host、host_is_trusted 会校验字符合法性:空值不再允许,Unix socket 地址被忽略,trusted_list 参数变为可选(:pr:3113`)。
  • Request.autocorrect_location_header 被弃用——需要绝对 URL 时直接设置 response.location(:issue:3247`)。
  • content_md5、pragma、accept_charsets(连同 CharsetAccept 类)等 header 属性被弃用:这些 header 要么长期未被使用,要么已在规范中正式弃用。
  • UserAgent 类与 Request.user_agent_class 被弃用:Request.user_agent 现在就是字符串,需要解析时自行处理(:issue:3271`)。
  • environ_property 以及 input_stream、remote_user、is_multithread、is_multiprocess、is_run_once 属性被弃用,改为直接从 request.environ 读取(:issue:3275`)。
  • testapp 模块及其 test_app 被弃用。
  • 新增 Request.sec_fetch_site、sec_fetch_mode、sec_fetch_user、sec_fetch_dest header 属性(:pr:3082`),源码见 src/werkzeug/sansio/request.py。
  • Response.make_conditional 即使面对不可满足的 Range 请求也会设置 Accept-Ranges header(:issue:3108`)。
  • Response 的 header 属性可设为 None 来删除该 header;Request 的 header 属性带缓存,后续访问不再重复解析。

2.5 路由系统的强化

  • Map 新增 subdomain_matching 参数(:issue:3005),用于关闭子域匹配。源码 <a href="https://link.gitcode.com/i/71b498eceb7c8d9073524d4c5eeefaec" target="_blank">src/werkzeug/routing/map.py</a> 中该参数为关键字参数,默认 True,且 subdomain_matching = subdomain_matching and not host_matching(开启 host_matching` 时自动关闭子域匹配)。
  • bind_to_environ 中若启用 host_matching,server_name 参数不再使用;若设置了 default_subdomain,当无法确定子域时会使用它。
  • 传入 Request 对象给 bind_to_environ 时,host 会对照 request.trusted_hosts 校验,非法 host 抛出 400(:issue:3007`)。
  • 向 map 添加与已有规则等价的规则时,抛出 DuplicateRuleError(:issue:3037`)。
  • int / float URL 转换器不再接受非 ASCII 数字;构建 URL 时会校验值;int 转换器的 fixed_digits 不计算负号;float 转换器拒绝溢出为 inf 的值,也不产生科学计数法、inf、nan(:issue:3242、:issue:3146)。

2.6 安全与密码学相关

  • ETag 与调试器 PIN 改用 SHA3-256(:pr:3164):因为 SHA-1 在 FIPS 140 环境中不可用。源码落点清晰可见——<a href="https://link.gitcode.com/i/fced22d18d3b494d5dc3f81672c3a505" target="_blank">src/werkzeug/http.py</a> 中 ETag 生成使用 hashlib.sha3_256(data, usedforsecurity=False).digest(),<a href="https://link.gitcode.com/i/93f8a2104c18c58424f0c6656bbb690e" target="_blank">src/werkzeug/debug/__init__.py</a> 与 <a href="https://link.gitcode.com/i/0b7ec749c03ad521a64b5d8fb5c93ae7" target="_blank">src/werkzeug/debug/__init__.py</a> 中 PIN 相关哈希同样使用 sha3_256`。注意:ETag 变化可能使部分缓存失效。
  • generate_password_hash 改用 secrets.token_urlsafe 生成盐,私有方法 gen_salt 被移除(:pr:3167`)。
  • unquote_etag 与 ETags.from_header 会丢弃无效的未加引号值;Request.if_range 遇到无效的弱 ETag 时丢弃该 header。
  • RequestCacheControl / ResponseCacheControl 现在继承 Mapping / MutableMapping(而非 ImmutableDict / dict);cache_control_property 函数与两个类的 cache_property 方法被弃用,改用 cc[key] 索引访问未知指令;向构造器传入 iterable 也被弃用,应传 mapping(parse_dict_header 与 from_header 返回的都是 mapping)。

2.7 测试与 multipart 解析

  • EnvironBuilder 可作为 with 上下文管理器使用(:pr:3101`)。
  • EnvironBuilder.close 会关闭 files 中所有打开的文件(之前每个 key 只关第一个);新增 EnvironBuilder.files.close 与 files.clear(clear 会调用 close)。
  • EnvironBuilder.files.add_file 传入 IO 对象时自动探测文件名。
  • multipart 解析失败时会关闭已解析的部分文件,避免 ResourceWarning;SpooledTemporaryFile 被恒定用于 multipart 文件解析。
  • 测试 Client 新增 query 方法,用于 QUERY 请求方法,源码见 src/werkzeug/test.py。
  • 开发服务器不再额外发送 100 Continue 响应,因为 Python 的基础服务器已经会发送(:issue:3138`)。

2.8 CSP 相关:新属性与旧属性弃用

3.2.0 新增了 required_trusted_types_for、trusted_types、upgrade_insecure_requests 三个 CSP 指令属性(:pr:3114);同时 prefetch_src、navigate_to、plugin_types 被弃用,因为对应指令已在规范中被弃用或移除(:pr:3114)。源码 src/werkzeug/datastructures/csp.py 中可以看到 upgrade_insecure_requests 为普通 csp_property,而 prefetch_src、navigate_to、plugin_types 的 csp_property 带有 deprecated="3.3" 标记。

三、3.1.x 维护版:安全修复与性能打磨

3.1 系列(2024-10 ~ 2026-04)主要是稳定与安全维护,但 3.1.0 本身是一个功能大版本。

3.1 系列的安全修复脉络

  • 3.1.6(2026-02-19):safe_join 在 Windows 上不再允许多段路径中的特殊设备名(:ghsa:29vq-49wr-vm6x`)。
  • 3.1.5(2026-01-08):safe_join 在 Windows 上不再允许更多特殊设备名(无论扩展名或周围空格)(:ghsa:87hc-h4r5-73f7`)。
  • 3.1.4(2025-11-28):safe_join 在 Windows 上禁止特殊设备名,防止通过 send_from_directory 读取这些设备;secure_filename 此前已阻止向这些设备写入(:ghsa:hgf8-39gv-g3f2)。同时,调试器 PIN 失败次数从 11 次改为 10 次(:pr:3020);multipart 解析器处理块边界处的 \r\n;改善 Watchdog reloader 的 CPU 占用。

这几条 GHSA 记录共同勾勒出一条重要线索:Werkzeug 对 Windows 保留设备名(如 CON、NUL、AUX 等)的防护是分阶段收紧的,最终在 3.1.4~3.1.6 间把 safe_join 的防护从"部分场景"推进到"任意扩展名、任意空格组合、多段路径"全覆盖。使用 send_from_directory / send_file 暴露用户可控路径的应用,应确保运行在 3.1.6+。

3.1.9 / 3.1.8 / 3.1.7:性能与鲁棒性

  • 3.1.9(Unreleased):ProfilerMiddleware 在 Python 3.15 上改用 profiling.tracing;uri_to_iri / iri_to_uri 保留空用户名、密码与端口 0;parse_options_header、parse_etags、parse_cookie 性能提升;get_host 校验端口范围;int 转换器在值超过 sys.get_int_max_str_digits() 时返回 404 而非 500;Podman 容器中调试器 PIN 生成改进;basic 认证解析禁止非 base64 字符;application/x-www-form-urlencoded 表单数据不再受 max_form_memory_size 限制(仅受 max_content_length 限制);单部分含 10+ 转换器的规则能正确赋值;非法的 Range 后缀长度 -0 不再被接受。
  • 3.1.8(2026-04-02):Request.host 与 get_host 在 header 缺失或含非法字符时返回空字符串(:issue:3142`)。
  • 3.1.7(2026-03-23):parse_list_header 保留部分带引号项、丢弃空项、未闭合引号返回空;WWWAuthenticate.to_header 无参数时不再产生尾随空格;Transfer-Encoding 作为集合解析;host 校验同 3.2.0 所述;修复 multipart 边界处换行的处理;merge_slashes 合并任意数量的连续斜杠。

3.1.3 ~ 3.1.1:小修复

  • 3.1.3:MultiDict 等接口的初始数据只接受 list / tuple / set 作为多值(此前放宽到任意 Collection 会误伤 bytes 这类应视为单值的类型);Host header 缺失回退到 SERVER_NAME 时,IPv6 地址会用 [] 包裹。
  • 3.1.2:TypeConversionDict.get 的 type 参数支持可调用对象;Headers 不再继承 MutableMapping(因其接口并不完全吻合)。
  • 3.1.1:修复 str(Request.headers) 恒为空的问题。

3.1.0:值得关注的"半大版本"

3.1.0(2024-10-31)包含一批面向未来的结构性变更:

  • 放弃 Python 3.8,移除先前弃用代码。
  • Request.max_form_memory_size 默认值从"无限制"改为 500kB:超过该大小的非文件表单字段会触发 RequestEntityTooLarge(:issue:2964`)。这是影响面很大的默认行为变更,处理大文本字段的应用需显式调高。
  • OrderedMultiDict / ImmutableOrderedMultiDict 正式弃用(3.2.0 移除)。
  • request.cache_control / response.cache_control 属性行为大幅调整(:issue:2980、:issue:2881):
    • 字典值恒为 str | None;设置属性会转换为字符串;设为 False 等价于 None;读取类型化属性时若转换抛 ValueError 则返回 None 而非字符串。
    • max_age 无值时返回 None 而非 -1。
    • 请求的 no_cache 是布尔值,出现时为 True 而非 "*";响应上仍是字符串。
    • max_stale、min_fresh、private 无值时返回 True / None 而非 "*"。
    • no_transform 变为布尔值(此前错误地恒为 None)。
    • 新增 must_understand、stale_while_revalidate、stale_if_error 属性。
  • 支持 Cookie CHIPS(Partitioned Cookies)(:issue:2797`)。
  • 新增 421 MisdirectedRequest 异常(:issue:2850`)。
  • PBKDF2 默认工作因子提高到 1,000,000 次迭代(:issue:2969)。源码 <a href="https://link.gitcode.com/i/eef922d2ae3d03719a732d2fc339669f" target="_blank">src/werkzeug/security.py</a> 中 generate_password_hash的 docstring 显示默认pbkdf2:sha256:600000`,并注明 3.1.0 后默认迭代数提升至 1,000,000。
  • datastructures 改为内联注解,移除 stub 文件。
  • MultiDict.getlist 的类型转换同时捕获 TypeError 与 ValueError。
  • MultiDict、Headers、CallbackDict 实现 | 与 |= 运算符,且不可变类型上禁止 |=。

四、3.0 系列:安全加固与 scrypt 默认化

  • 3.0.1(2023-10-24):修复大 multipart 部分解析缓慢可能导致的 DoS 攻击——这是 3.0 系列最重要的安全修复之一,与 2.3.8 是同一问题(2.3.x 分支也同步修复)。
  • 3.0.6(2024-10-25):修复解析大非文件字段时 max_form_memory_size 的应用方式(:ghsa:q34m-jh98-gwm2);safe_join捕获 Python < 3.11 上ntpath.isabs` 未拦截的 Windows 路径。
  • 3.0.5:Watchdog reloader 忽略"关闭但未写"事件;IPv6 scope 地址日志;忽略无效的 authorization 参数;Python 3.13 下调试器 PIN 生成兼容。
  • 3.0.4:恢复"解析含非法 UTF-8 字节的 multipart/x-www-form-urlencoded 数据时无表单数据而非 413 错误"的行为;parse_options_header 对未闭合引号字符串提速;调试器 PIN 认证在跨线程/进程时同步失败计数;Python < 3.13 处理 SSLEOFError。
  • 3.0.3:开发服务器调试器请求只允许 localhost、.localhost、127.0.0.1 或指定主机名(:ghsa:2g68-c3qc-8985);reloader 对 sys.path中的"" 更健壮;adhoc TLS 证书格式改进;itms-services` URI 正确处理。
  • 3.0.2:merge_slashes=False 时重复斜杠请求返回 NotFound;TypeConversionDict.get() 的 TypeError 处理与 ValueError 对齐;MultiPartParser.parse 返回类型更精确;转换器参数无法解析时报错。
  • 3.0.0:移除先前弃用代码;弃用 __version__ 属性(改用特性检测或 importlib.metadata.version("werkzeug"));generate_password_hash 默认改用 scrypt(:issue:2769);向 ProfilerMiddleware的filename_format回调传入的 WSGI environ 新增"werkzeug.profiler"项(含elapsed与time);PathConverter` 明确标记为非 path isolating。

五、2.3 系列:API 重构高峰

2.3.x(2023-02 ~ 2023-11)是 Werkzeug 近年 API 变化最密集的版本段。

5.1 2.3.0 的主线变更

  • 放弃 Python 3.7。
  • 全面弃用向"期望字符串"的位置传 bytes,以及许多地方的 charset / errors 参数(:issue:2602`):这是从 Python 2 迁移时代遗留的清理,移除了大量实例检查与编码循环开销;官方建议始终使用 UTF-8。
  • 弃用 werkzeug.urls 模块(uri_to_iri / iri_to_uri 除外),改用 urllib.parse。
  • URL 百分号编码的安全字符集按 WhatWG URL 标准与 RFC 3986 更新;下载文件名的 Unicode 百分号编码安全字符集同步更新。
  • Authorization / WWWAuthenticate 数据结构重构(:issue:1769):两个类都具备 type、parameters、token 属性(token支持Bearer这类单不透明令牌方案);不再是dict,但仍支持 auth[key]、auth.key、auth.get(key)、key in auth;两个类都有 from_header 类方法,parse_authorization_header/parse_www_authenticate_header 被弃用;WWWAuthenticate.set_basic/set_digest被弃用(改为创建实例赋给response.www_authenticate`);可赋实例列表以设置多个 header 值。
  • parse_cookie / dump_cookie 重构(:pr:2637):分别提速最高 40% / 60%;传 bytes 与 charset 参数弃用;dump_cookie允许无点号的domain并剥掉前导点;不再无谓地默认设置path="/"`。
  • 测试客户端 cookie 实现重构:弃用 cookie_jar(不再用 http.cookiejar 存储);按 domain 与 path 匹配发送 cookie(默认 localhost 与 /);新增 get_cookie 方法;cookie 有 decoded_key / decoded_value 属性;set_cookie / delete_cookie 的首个位置参数 server_name 弃用。
  • request.max_content_length 在访问流时立即检查,并在读取流的全过程持续检查(而非仅表单解析时),修复客户端"连接重置"而非 413 的问题。
  • 开发服务器会耗尽请求流至 10GB 或 1000 次读取,让客户端能看到 413 而非连接重置;丢弃含下划线 _ 的 header 键(在 WSGI 中与连字符 - 有歧义)。
  • PBKDF2 默认迭代提升到 600,000(3.1.0 再提升至 1,000,000)。
  • parse_options_header 提速 2-3 倍并遵循 RFC 9110;parse_accept_header 按 RFC 9110 实现,丢弃非法 q 值。
  • Request.get_json() 在 Content-Type 不是 application/json 时抛 415 而非 400。
  • 转换器 part_isolating 在 regex 含 / 时默认 False;自定义转换器正则可含捕获组。
  • reloader 可识别 python 的参数(如 -X dev),仅在 Python >= 3.10 上可用。
  • generate_password_hash 支持 scrypt;明文哈希方法弃用,仅支持 scrypt 与 pbkdf2。

5.2 2.3.1 ~ 2.3.8 的维护修复

  • 2.3.8(2023-11-08):与 3.0.1 相同的大 multipart 解析 DoS 修复(2.3.x 分支同步)。
  • 2.3.7:改用 flit_core 作为构建后端(与当前 pyproject.toml 的 flit_core.buildapi 一致);修复 multipart 解析;URL 规则不以斜杠开头时给出更清晰的报错。
  • 2.3.5:Python 3.12 兼容;Authorization.from_header 处理非法 base64;iri_to_uri 传 bytes 改为警告而非报错;HTTP 请求头数字解析只接受 ASCII 数字。
  • 2.3.4:Authorization.from_header / WWWAuthenticate.from_header 检测以 base64 padding(=)结尾的 token;max_form_parts 限制仅用于 multipart;Response 保留 itms-services 等非法 URL scheme。
  • 2.3.3:修复大 multipart 解析(移除非法前导换行、恢复解析速度);cookie Path 默认重新设为 /。
  • 2.3.2:测试客户端正确解析 cookie Expires;max_content_length 仅在服务器设置 wsgi.input_terminated 时对流式请求强制生效。
  • 2.3.1:构建 URL 与测试请求中百分号编码 +;cookie 值不引号化 RFC 6265 定义的字符;Authorization / WWWAuthenticate 支持相等比较。

六、2.2 系列:状态机路由器与 DoS 防护

  • 2.2.0:新增基于状态机的更快 URL 匹配路由器(:pr:2433);自定义转换器若要匹配 /,必须设置类变量 part_isolating = False;弃用 get_script_name、get_query_string、peek_path_info、pop_path_info、extract_path_info;MarkupSafe 成为正式依赖;新增调试器 preserve_context机制;新增 sans-IO 的is_resource_modified、parse_cookie、get_content_length`。
  • 2.2.1:/path/ 在规则禁用 strict slashes 时匹配 /path;部分部分匹配(如 /2df 匹配 /<int>)不再允许;静态部分加权使更简单的路由优先匹配。
  • 2.2.2:恢复 2.1 的 strict_slashes == False 行为;开发服务器启动时总是显示"不可用于生产"警告。
  • 2.2.3:规定 multipart 部件数量上限,默认 1000,超过即抛 RequestEntityTooLarge,缓解"大量 form/file 部件导致资源使用失衡"的 DoS 攻击。

七、2.1 系列:开发服务器 HTTP/1.1 化

  • 2.1.0:放弃 Python 3.6;开发服务器在启用 threaded 或 processes 时使用 HTTP/1.1(支持 keep-alive 与 chunked 流式响应);流式响应使用 Transfer-Encoding: chunked;移除了一批历史遗留(shutdown 函数、mixin、python -m werkzeug.serving CLI、Href、HTMLBuilder 等);Request.get_json() 对非 JSON Content-Type 抛 400;Response.autocorrect_location_header 默认关闭。
  • 2.1.1:ResponseCacheControl.s_maxage 像 max_age 一样转换为 int。
  • 2.1.2:开发服务器对 1xx、204、304、HEAD 响应不设置 chunked;异常与重定向的响应 HTML 以 <!doctype html> 与 <html lang=en> 开头;禁用 keep-alive(Python http.server 支持不充分)。

八、2.0 系列:告别 Python 2,迈向 sans-IO

2.0.0(2021-05-11)是划时代版本:

  • 放弃 Python 2 与 3.5。
  • 所有 datetime 值改为带 tzinfo=timezone.utc 的时区感知值。
  • 合并所有 request/response mixin 到单一 Request / Response 类。
  • JSON 支持不再依赖 simplejson,改用 json_module 覆盖机制;Response.get_json() 不再缓存。
  • 新增 send_file / send_from_directory(源自 Flask 实现);send_file 默认 conditional=True、max_age=None(Cache-Control: no-cache),支持 download_name、etag="string"。
  • 测试客户端请求方法恒返回 TestResponse(含 request 与 history 属性);新增 auth 参数。
  • 抽取 sans-IO 的 Request / Response 基类(非公开 API,为让 ASGI 框架使用 Werkzeug 铺路);multipart 解析重构为 sans-IO 模式,大文件上传解析显著提速。
  • Local 在 Python 3.7+ 改用 ContextVar;LocalProxy 完整匹配数据模型特殊方法(含 r-ops、in-place、async、__class__ 代理)。
  • ETag 与调试器 PIN 从 MD5 改用 SHA-1(MD5 在 FIPS 140 环境不可用)——3.2.0 又升级为 SHA3-256。
  • PBKDF2 迭代提升至 260,000,盐长度从 8 增至 16,改用 secrets 生成盐。
  • request.values 对 GET 请求不再包含 form;开发服务器在 environ 中暴露 werkzeug.socket 供 WebSocket upgrade 使用。

2.0.1 ~ 2.0.3 主要是类型标注修复(cached_property 泛型化、send_file 的 max_age 可调用对象等)与 ProxyFix 的 IPv6 支持。

九、1.0 系列:模块化导入与 CSP 支持

1.0.0(2020-02-06)的关键变化:

  • 移除 werkzeug 顶级模块的大部分属性,改为直接导入(如 from werkzeug.urls import url_quote)。升级路径是先装 0.16 查看弃用警告。
  • 请求 cookie 解析为 MultiDict(捕获同名 cookie 的所有值,cookies[key] 返回第一个,getlist(key) 返回全部)。
  • 新增 Response.content_security_policy 数据结构以支持 CSP header。
  • 新增 response.cache_control.immutable 标志、Map / Rule 的 merge_slashes 选项(默认开启)、Map.lock_class、WebSocket 规则匹配与构建。
  • 429 TooManyRequests / 503 ServiceUnavailable 异常支持 retry_after 参数;新增 103/208/306/425/506/508/511 状态码。
  • Headers 新增 update、setlist、setlistdefault;FileStorage.save 支持 pathlib / PathLike。
  • RequestRedirect 在 0.15.0 已从 301 改为 308(保留方法与请求体)。

十、0.x 时代:从零构建 WSGI 库的关键里程碑

0.x 阶段(2007-12 ~ 2020-01)奠定了 Werkzeug 的核心架构,重要节点包括:

  • 0.1(2007-12):初始发布,含 cached_property(原 lazy_property)、import_string、dump_cookie / parse_cookie、DispatcherMiddleware、MapAdapter 等至今仍在的基础设施。
  • 0.2:新增 AnyConverter、securecookie、get_response()、dump_cookie / parse_cookie。
  • 0.5(2009-04):自研服务器取代 wsgiref;新增 MIMEAccept / CharsetAccept、secure_filename、run_simple 的 passthrough_errors、实验性 multipart 解析器;EnvironBuilder 统一了 create_environ / Client / from_values。
  • 0.6(2010-02):FileStorage 提供 multipart headers;开发服务器支持 SSL;MapAdapter.match 支持 return_rule。
  • 0.7(2011-07):路由系统支持 host 匹配与查询参数保留;safe_join、is_xhr、accept_json 加入;Range / If-Range / Content-Range 解析支持。
  • 0.9(2013-06):LimitedStream.tell;ETag 支持;send_from_directory 前身逻辑;generate_password_hash 支持任意 hashlib 算法。
  • 0.10(2015-01):UUID 转换器;stdlib ssl 取代 OpenSSL;MapAdapter.match 区分 / 与空路径。
  • 0.11(2015-11):调试器 PIN 认证引入(因为太多人把调试器跑在生产环境);reloader_paths 选项。
  • 0.14(2017-12):SameSite cookie 属性;ProxyMiddleware;HTTP 异常被 Request.application 自动捕获。
  • 0.15(2019-03):URL 构建提速约 7 倍(每个 Rule 编译优化的构建函数);Unauthorized 支持 www_authenticate 参数;RequestRedirect 改 308;Location 自动纠偏基于当前路径;调试器弃用 jQuery 序列(0.15 用 jQuery 3.3.1,2.0.0 彻底移除)。
  • 0.16(2019-09):弃用顶级属性导入,为 1.0 的模块化导入铺路;contrib 模块开始拆分(LintMiddleware → werkzeug.middleware.lint,ProfilerMiddleware → werkzeug.middleware.profiler,ProxyFix → werkzeug.middleware.proxy_fix,cache/securecookie 拆分为独立项目)。

从源码结构看,这一演进至今仍清晰可见:werkzeug.contrib 时代的模块如今都以独立子包形式存在于 src/werkzeug/middleware 与 src/werkzeug/datastructures 中。

十一、升级指南:从 CHANGES.rst 提炼的检查清单

基于上述版本脉络,升级 Werkzeug 时可按以下清单自查:

  1. 先看 Python 版本:3.2.0 需 Python >= 3.10;3.1.x 需 >= 3.9;3.0.x 需 >= 3.8。
  2. 搜索弃用 API:用 python -W default::DeprecationWarning 运行测试(0.15 时代的建议至今适用),重点排查 OrderedMultiDict、ImmutableList/Dict、TypeConversionDict、environ_property、UserAgent、testapp、werkzeug.urls(除 IRI 转换函数)、parse_*_header 函数(改用 X.from_header)。
  3. 关注默认行为变化:
    • redirect() 默认 303(3.2.0);
    • Request.max_form_memory_size 默认 500kB(3.1.0);
    • generate_password_hash 默认 scrypt(3.0.0),pbkdf2 迭代数随版本递增;
    • cache_control 属性取值的 None/布尔/字符串语义(3.1.0);
    • 表单与请求数据强制 UTF-8(2.3.0 起)。
  4. 安全修复落点:运行 3.1.6+(safe_join Windows 防护)、3.1.0+(multipart DoS 防护)、3.0.1+/2.3.8+(大 multipart 解析 DoS)。若使用 send_from_directory,务必升级到 3.1.6 以上。
  5. ETag 缓存失效预期:3.2.0 起 ETag 改用 SHA3-256,CDN 与浏览器缓存可能整体失效一次,属预期行为。

十二、如何继续深入

CHANGES.rst 中的每一条变更都能在源码中找到落点,建议结合以下文件交叉阅读:

对于每个版本的完整原始条目,直接翻阅仓库根目录的 CHANGES.rst,其中保留了每项变更对应的 issue/PR 编号,可作为追溯讨论上下文的第一手索引。

登录后查看全文
werkzeug