Werkzeug 版本变更日志深度解读:从 3.2.0 到 0.1 的关键演进与源码印证
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本就基于 Pythondict,天然保序。
同时,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 下:
- accept.py 的
Accept.from_header/to_header; - auth.py 的
Authorization/WWWAuthenticate; - cache_control.py 的
RequestCacheControl/ResponseCacheControl; - csp.py、etag.py、range.py 以及 structures.py。
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_destheader 属性(:pr:3082`),源码见 src/werkzeug/sansio/request.py。 Response.make_conditional即使面对不可满足的 Range 请求也会设置Accept-Rangesheader(: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/floatURL 转换器不再接受非 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这类应视为单值的类型);Hostheader 缺失回退到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.servingCLI、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(Pythonhttp.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):
SameSitecookie 属性;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 时可按以下清单自查:
- 先看 Python 版本:3.2.0 需 Python >= 3.10;3.1.x 需 >= 3.9;3.0.x 需 >= 3.8。
- 搜索弃用 API:用
python -W default::DeprecationWarning运行测试(0.15 时代的建议至今适用),重点排查OrderedMultiDict、ImmutableList/Dict、TypeConversionDict、environ_property、UserAgent、testapp、werkzeug.urls(除 IRI 转换函数)、parse_*_header函数(改用X.from_header)。 - 关注默认行为变化:
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 起)。
- 安全修复落点:运行 3.1.6+(
safe_joinWindows 防护)、3.1.0+(multipart DoS 防护)、3.0.1+/2.3.8+(大 multipart 解析 DoS)。若使用send_from_directory,务必升级到 3.1.6 以上。 - ETag 缓存失效预期:3.2.0 起 ETag 改用 SHA3-256,CDN 与浏览器缓存可能整体失效一次,属预期行为。
十二、如何继续深入
CHANGES.rst 中的每一条变更都能在源码中找到落点,建议结合以下文件交叉阅读:
- src/werkzeug/utils.py:
redirect默认 303 与状态码语义说明; - src/werkzeug/routing/map.py:
subdomain_matching参数; - src/werkzeug/datastructures:
from_header/to_header的全套实现(accept、auth、cache_control、csp、etag、range、structures); - src/werkzeug/datastructures/csp.py:CSP 新旧属性;
- src/werkzeug/security.py:scrypt / pbkdf2 默认参数;
- src/werkzeug/http.py 与 src/werkzeug/debug/init.py:SHA3-256 的 ETag / PIN 哈希;
- src/werkzeug/test.py:测试客户端的
query方法; - pyproject.toml:当前版本、Python 下限与依赖约束。
对于每个版本的完整原始条目,直接翻阅仓库根目录的 CHANGES.rst,其中保留了每项变更对应的 issue/PR 编号,可作为追溯讨论上下文的第一手索引。