Werkzeug 版本演进全解析:从 0.1 到 3.2.0 的变更史与技术路线图
Werkzeug 版本演进全解析:从 0.1 到 3.2.0 的变更史与技术路线图
本文以仓库根目录的 CHANGES.rst(由 docs/changes.rst 通过
.. include:: ../CHANGES.rst引入)为骨架,逐版本梳理 Werkzeug —— 这套 "The comprehensive WSGI web application library" —— 十余年的演进脉络。读完本文,你将掌握每个版本的核心变更、弃用与移除清单、安全修复要点、路由/表单/测试客户端/开发服务器等核心模块的能力变迁,并能结合仓库源码(src/werkzeug)与测试(tests)深入理解每一项变更背后的实现依据。这份变更记录本身就是一份绝佳的升级指南与技术决策档案:任何一次从旧版本迁移到新版本,都可以对照它逐条核查自己的代码是否踩中移除项或行为变化点。
一、文档定位:一份可当"升级圣经"使用的变更史
docs/changes.rst 本身只有三行——标题加一个 include 指令,真正的正文全部来自仓库根目录的 CHANGES.rst。这份文件按版本倒序组织:最新版本在最上方,最早的 0.1 版本在文件末尾,合计覆盖从 2007 年 12 月(0.1,代号 Wictorinoxger)到当前 3.2.0 的全部历史。
从 pyproject.toml 可以看到,当前仓库版本为 3.2.0.dev,要求 Python >= 3.10,唯一硬依赖是 markupsafe>=3.0.3(对应 3.2.0 的"最低 MarkupSafe 版本提升"条目),watchdog>=6 是可选依赖(对应 Watchdog reloader 的最低版本要求)。这组版本与依赖信息与 CHANGES.rst 顶部完全吻合,阅读变更记录时可以直接以仓库当前状态为参照物。
这份文档的价值有三层:
- 升级迁移清单:每个版本都列出了"移除此前已弃用的代码"清单,以及新增弃用项,升级前逐条对照即可规避踩坑;
- 安全公告索引:从 GHSA 编号(如
:ghsa:29vq-49wr-vm6x、:ghsa:87hc-h4r5-73f7、:ghsa:f9vj-2wh5-fj8j、:ghsa:2g68-c3qc-8985)可以反查每个安全修复的详情; - 架构演进档案:sans-IO 重构、状态机路由器、类型注解全面化等重大架构决策都留有明确的时间戳。
二、3.2.0:API 现代化与大规模弃用
3.2.0 是当前未发布的最新版本(在 CHANGES.rst 中列于最顶端),核心主题是"收紧类型系统、清理历史包袱"。
2.1 Python 版本与依赖门槛
- Drop support for Python 3.9(:pr:
3098):3.2.0 起最低支持 Python 3.10; - 移除此前已弃用的代码(:pr:
3099):其中明确删除了OrderedMultiDict与ImmutableOrderedMultiDict——因为底层MultiDict本身已保持插入顺序,有序变体不再有意义(对应 3.1.0 的弃用声明); - 最低依赖版本提升:MarkupSafe 3.0.3、Watchdog 6.0。
2.2 数据结构与类型体系收紧
3.2.0 对 werkzeug.datastructures 做了系统性的类型重构,这是理解本版本的关键:
ImmutableList/ImmutableListMixin弃用:Accept改为继承Sequence,类型标注请改用tuple、Sequence、MutableSequence;ImmutableDict/ImmutableDictMixin弃用:改用Mapping与MutableMapping;UpdateDictMixin弃用:改用CallbackDict;TypeConversionDict/ImmutableTypeConversionDict弃用:带类型转换的get仍然保留在MultiDict与ImmutableMultiDict上;RequestCacheControl/ResponseCacheControl改继承Mapping/MutableMapping(不再继承ImmutableDict/dict);cache_control_property函数与两个类的cache_property方法弃用:未知指令请用索引访问cc[key];- 向这两个类传可迭代对象已弃用:请传 mapping(
parse_dict_header的返回值及from_header方法的输入正是 mapping)。
一个值得注意的行为变化:Request.parameter_storage_class、dict_storage_class、list_storage_class 属性,以及 parse_cookie、parse_form_data、FormDataParser 的 cls 参数全部弃用。Request.form、files、args、cookies 将恒为 ImmutableMultiDict,Request.access_route 恒为 Sequence。原因在变更记录里写得很清楚:"这些此前允许被覆写以提供有序数据结构,但 Python 的 dict 现在已保证顺序"(:pr:3169)。在源码中可见其实现痕迹:src/werkzeug/wrappers/request.py 里 _get_form 等方法仍保留了对 parameter_storage_class 的兼容分支,但会触发 DeprecationWarning,并注明"将在 Werkzeug 3.3 中移除,将恒为 ImmutableMultiDict"。
2.3 结构化 Header 的统一入口:from_header / to_header
3.2.0 一个极具指导意义的架构变更(:pr:3116):werkzeug.datastructures 中所有结构化 header 类都增加了 from_header 类方法与 to_header 方法,相应地 werkzeug.http 中一批解析函数被弃用:
dump_csp_headerparse_accept_headerparse_cache_control_headerparse_content_range_headerparse_csp_headerparse_etagsparse_if_range_headerparse_range_headerparse_set_header
变更记录给出的理由直指设计动机:"改善静态类型,并减少循环导入"。这与 2.3.0 中 Authorization/WWWAuthenticate 引入 from_header 的路径一脉相承——Werkzeug 正在把"解析函数 + 数据结构"的二元 API 收敛为"结构类自包含解析与序列化"的单一入口。
配套行为变化还有:
- 空
ContentRange视为 false,units恒为字符串,构造参数带默认值;set/unset方法弃用,改为直接设置/删除response.content_range; HTTP_STATUS_CODES弃用,改用 Python 内置http.HTTPStatus;原因短语从大写改为更常见的标题大小写(:pr:3139)。
2.4 Request/Response 属性的清理与安全强化
一批长期闲置或已被规范废弃的 header 属性被弃用:
Request/Response的content_md5(:pr:3158)、Request.pragma(:pr:3160)、Request.accept_charsets与CharsetAccept类(:pr:3161);UserAgent类与Request.user_agent_class弃用(:issue:3271):Request.user_agent现在就是字符串,需要时可直接自行解析;environ_property函数及Request.input_stream、remote_user、is_multithread、is_multiprocess、is_run_once属性弃用(:issue:3275):直接访问request.environ;testapp模块及其test_app弃用;Request.autocorrect_location_header属性弃用(:issue:3247):需要绝对 URL 时直接设置response.location。
CSP 指令侧同步更新:prefetch_src、navigate_to、plugin_types 三个属性弃用(:pr:3114,对应指令已从规范中弃用或移除),同时新增了 required_trusted_types_for、trusted_types、upgrade_insecure_requests 指令的属性支持。
2.5 redirect 默认行为变更:302 → 303
这是一个对应用行为有直接影响的 breaking change(:pr:3092):werkzeug.utils.redirect 的默认状态码从 302 改为 303。其语义是:303 告诉客户端"无论如何都切换为 GET",而 302 在旧客户端实现中只把 POST 切为 GET、其他方法保持不变。
源码佐证清晰可见:src/werkzeug/utils.py 中 def redirect(location: str, code: int = 303, ...),其 docstring 完整说明了各状态码语义:303 See Other 始终用 GET;307 Temporary Redirect 保留当前方法;308 Permanent Redirect 保留方法且永久生效;302/301 因客户端实现不一致而被 307/308 取代。变更记录补充说明:这保留了 GET 与 POST 重定向的既有行为,同时正确适配了 HTMX 等前端库。
配套的测试客户端行为同步调整(均为 :pr:3092):
- 重定向切换为 GET 时,清理更多请求体信息;
- 仅当原请求是 POST 时,测试客户端才把 301/302 切换为 GET;
- 305 不再被当作重定向处理(已从 HTTP 规范中移除);
EnvironBuilder.close关闭files中每个键的全部文件(此前只关第一个);EnvironBuilder可作为with上下文管理器使用(:pr:3101)——源码中__enter__/__exit__已实现,close关闭所有文件;EnvironBuilder.files.add_file在传入 IO 对象时会自动探测文件名,新增files.close方法,且files.clear会调用close。
2.6 路由、URL 转换器与 multipart 解析
Map新增subdomain_matching参数(:issue:3005):可关闭子域匹配;bind_to_environ在启用host_matching时忽略server_name;设置了default_subdomain时,无法确定子域就使用它。源码 src/werkzeug/routing/map.py 中subdomain_matching: bool = True,且self.subdomain_matching = subdomain_matching and not host_matching——子域匹配默认开启、但与 host_matching 互斥,二者不可同时生效;Map.bind_to_environ传入 Request 对象时校验 host 是否在request.trusted_hosts中,非法 host 返回 400(:issue:3007);- 新增
DuplicateRuleError:向 Map 添加与既有 rule 相等的 rule 时抛出(:issue:3037),定义在 src/werkzeug/routing/exceptions.py; int/floatURL 转换器不再接受非 ASCII 数字;to_url(构建 URL)时进行校验;int转换器的fixed_digits不再把负号计入位数;float转换器拒绝溢出到inf的值、也不产生科学计数法/inf/nan(:issue:3242、:issue:3146)。源码 src/werkzeug/routing/converters.py 中IntConverter.to_url会先int(value)再校验 signed/min/max/fixed_digits 宽度,FloatConverter校验math.isfinite;- multipart 解析失败时关闭已解析的文件,避免
ResourceWarning;SpooledTemporaryFile恒用于 multipart 文件解析(:pr:3101)。
2.7 其他 3.2.0 亮点
Request.sec_fetch_site、sec_fetch_mode、sec_fetch_user、sec_fetch_dest四个 header 属性新增(:pr:3082);Response.make_conditional即使不是可满足的 range 请求也会设置Accept-Ranges(:issue:3108);Request.host、get_host、host_is_trusted校验字符合法性,空值不再允许,忽略 Unix socket 地址,host_is_trusted的trusted_list参数变为可选(:pr:3113);- 开发服务器不再额外发送
100 Continue响应(Python 基础服务器已发送); Request.if_range遇到无效弱 ETag 时丢弃该 header(:pr:3163);- ETag 与调试器 PIN 改用 SHA3-256(替代 SHA-1,后者在 FIPS 140 下不可用),可能导致缓存失效因为 ETag 值变化(:pr:
3164); generate_password_hash用secrets.token_urlsafe生成盐,移除私有gen_salt方法(:pr:3167);- 测试
Client新增query方法,对应QUERY请求方法(src/werkzeug/test.py 中def query(self, *args, **kw) -> TestResponse); unquote_etag与ETags.from_header丢弃无效的未加引号值;cached_property在尚未访问缓存时也可被删除;- Request 的 header 属性加缓存,后续访问跳过重复解析;
- Response 的 header 属性可设为
None来删除该 header。
三、3.1.x 系列:稳定期的小步快跑与安全加固
3.1.x 是 2024 年底到 2026 年初的稳定维护系列,条目多为行为修正与安全补丁,非常适合用来理解"小版本里藏着的坑"。
3.1.0(2024-10-31):最后一个特性型小版本
- Drop Python 3.8 支持,并移除先前已弃用代码(:pr:
2966/2967); Request.max_form_memory_size默认从无限改为 500kB(:issue:2964):非文件表单字段超过该大小将触发RequestEntityTooLarge。源码佐证:src/werkzeug/wrappers/request.py 中max_form_memory_size: int | None = 500_000,注释说明文件部分不受此限(达到上限移入磁盘);cache_control属性行为大幅调整(:issue:2980等):字典值恒为str | None;max_age无值时返回None(不再是-1);no_cache在请求侧为布尔(存在即为True,不再是"*"),响应侧仍为字符串;max_stale/min_fresh/private无值时返回True/None(不再"*");no_transform修正为布尔;新增must_understand、stale_while_revalidate、stale_if_error属性;- Cookie CHIPS(Partitioned Cookies)支持(:issue:
2797); - 新增 421
MisdirectedRequestHTTP 异常(:issue:2850); - PBKDF2 默认工作因子提升到 1,000,000 次迭代(:issue:
2969); - datastructures 内联类型注解,移除 stub 文件(:issue:
2970); MultiDict.getlist类型转换时同时捕获TypeError与ValueError(:issue:2976);- 为
MultiDict、Headers、CallbackDict实现|与|=运算符,不可变类型禁用|=(:issue:2977)。
3.1.1~3.1.4:定向修复
- 3.1.1:修复
str(Request.headers)恒为空的问题(:issue:2985); - 3.1.2:
TypeConversionDict.get的type参数允许 callable;Headers不再继承MutableMapping(不完全匹配该接口,:issue:2989); - 3.1.3:
MultiDict传多值仅接受list/tuple/set(此前改为接受任意Collection,但会误伤bytes等单值类型);Host头缺失且回退到SERVER_NAME时,IPv6 地址会被[]包裹以匹配 Host 头格式(:issue:2993); - 3.1.4(2025-11-28):Windows 上
safe_join禁止特殊设备名(防止经send_from_directory读取,secure_filename早已阻止写入,:ghsa:hgf8-39v-g3f2);调试器 PIN 在 10 次失败后锁定(而非 11 次);multipart 解析器处理块边界处的\r\n;Watchdog reloader 降低 CPU 占用;Request.json注解更精确;HTTPException.get_response的注解与文档更清晰地区分 WSGI 与 sans-IO 响应。
3.1.5~3.1.9:安全补丁与性能
- 3.1.5(2026-01-08):
safe_join在 Windows 上禁止更多特殊设备名(:ghsa:87hc-h4r5-73f7);multipart 解析器正确拆分块边界处的\r\n(修复上一版导致的错误 content length);修复DebuggedApplication(pin_security=False)的AttributeError; - 3.1.6:Windows
safe_join多段路径中的设备名(:ghsa:29vq-49wr-vm6x); - 3.1.7:
parse_list_header保留部分引用的条目、丢弃空条目、未闭合引用返回空;WWWAuthenticate.to_header无参数时不产生尾随空格;Transfer-Encoding按集合解析;host 相关校验与 Unix socket 处理(同 3.2.0 条目,:pr:3113);merge_slashes合并任意数量的连续斜杠; - 3.1.8(2026-04-02):
Request.host/get_host在 header 缺失或含非法字符时返回空字符串; - 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转换器超长值时返回 404 而非 500;调试器 PIN 在 Podman 的 cgroup 数据下生成更可靠;basic auth 解析拒绝非 base64 字符;application/x-www-form-urlencoded表单数据不再受max_form_memory_size限制(仅受max_content_length);LimitedStream.readinto少读时不再调整缓冲区;10+ 转换器单段规则正确赋值;非法 Range 后缀长度-0不再被接受。
四、3.0 系列:Python 版本门槛与安全基线确立
3.0.x 集中体现了"破坏性大版本 + 安全补丁维护"的节奏:
- 3.0.0(2023-09-30):移除先前已弃用代码;弃用
__version__属性(改用特性检测或importlib.metadata.version("werkzeug"));generate_password_hash默认算法改为 scrypt(:issue:2769);ProfilerMiddleware的filename_format函数可收到"werkzeug.profiler"environ 键(含elapsed/time);显式将 PathConverter 标记为非 path isolating; - 3.0.1(2023-10-24):修复大 multipart 解析缓慢问题,潜在 DoS 修复;
- 3.0.2:
merge_slashes=False时重复斜杠请求对单斜杠路由返回 NotFound;TypeConversionDict.get()的TypeError处理与ValueError对齐;converter 参数无法解析时抛错; - 3.0.3(2024-05-05):开发服务器仅允许
localhost、.localhost、127.0.0.1或指定主机名发起调试器请求(:ghsa:2g68-c3qc-8985);reloader 对sys.path中的""更健壮;adhoc 开发证书 TLS 格式改进;Rule.endpoint类型注解改为Any; - 3.0.4:
multipart/x-www-form-urlencoded含非法 UTF-8 字节时恢复为"不解析出表单数据"而非 413;调试器 PIN 认证跨线程/进程同步失败计数;开发服务器处理 Python < 3.13 的SSLEOFError; - 3.0.5:Watchdog reloader 忽略"关闭但未写入"事件;IPv6 scope 地址日志;忽略无效 authorization 参数;
SharedDataMiddleware类型注解改进;Python 3.13 下 UID 无关联名称时的调试器 PIN 兼容; - 3.0.6(2024-10-25):
max_form_memory_size应用于大非文件字段的解析方式修复(:ghsa:q34m-jh98-gwm2);Windowssafe_join补充 Python < 3.11 的ntpath.isabs遗漏路径(:ghsa:f9vj-2wh5-fj8j)。
五、2.x 时代:sans-IO 重构、状态机路由与性能工程
2.x 是架构性变化最密集的时期,理解这段历史有助于把握当前代码结构(sansio/、routing/matcher.py 等目录的存在都源于此)。
5.1 2.0(2021-05-11):告别 Python 2
- Drop Python 2 与 3.5 支持(:pr:
1693); - 弃用
format_string、bind_arguments/validate_arguments、HTMLBuilder、escape/unescape(改用 MarkupSafe)、python -m werkzeug.servingCLI、environ["werkzeug.server.shutdown"]、useragents模块与内置 UA 解析器(建议子类化user_agent.UserAgent并设置Request.user_agent_class); - 所有
datetime值均带tzinfo=timezone.utc,涉及http.parse_date的全部属性(Request.date/if_modified_since/if_unmodified_since、Response.date/expires/last_modified/retry_after等); - Request/Response mixin 全部合并进单一类,
BaseRequest/BaseResponse的 isinstance 检查会告警; - JSON 支持不再依赖 simplejson(通过
Request.json_module/Response.json_module覆写);Response.get_json()不再缓存结果; Response.freeze()未设置 ETag 时自动生成;send_file/send_from_directory从 Flask 移植而来,download_name替代 Flask 的attachment_filename;send_file默认conditional=True、max_age=None;generate_password_hash默认 PBKDF2 迭代从 150000 提至 260000,盐长从 8 增至 16,用secrets生成盐;- 新增 sans-IO 的 Request/Response 基类(非公开 API,为 ASGI 框架铺路);
Local在 Python 3.7+ 用ContextVar替代threading.local; request.values不再包含 GET 请求的 form(防止坏缓存代理缓存表单数据)。
5.2 2.1(2022-03-28):本地上下文与现代 HTTP
- 要求 gevent/eventlet 配套 greenlet>=1.0 或 PyPy>=7.3.7;
- 移除非标准的
werkzeug.server.shutdown、user_agent解析器内建、python -m werkzeug.servingCLI、locals.get_ident、cookie_date、pbkdf2_hex/pbkdf2_bin/safe_str_cmp(改用hashlib/hmac)、Href、HTMLBuilder、invalidate_cached_property(改用del obj.attr)等; - 开发服务器升级为 HTTP/1.1:启用 keep-alive 与 chunked 流式响应(
threaded/processes开启时),流式响应使用Transfer-Encoding: chunked; cached_property支持__slots__(配合_cache_{name}槽位);TestResponse.text快捷属性;append_slash_redirect默认状态码改为 308(保留请求体);Response.autocorrect_location_header默认关闭(Location 保持相对路径);Request.get_json()对非application/json的 Content-Type 抛 400;run_simple对 "address already in use" 给出处理指引。
5.3 2.2(2022-07-23):MarkupSafe、状态机路由与调试器上下文
- 加入 MarkupSafe 依赖,渲染 HTML 时用它转义(:issue:
2419); - 新增基于状态机的更快 URL 匹配路由器(:pr:
2433):自定义 converter 若需匹配/必须设置part_isolating = False(matcher.py中StateMachineMatcher即此产物); - 新增
werkzeug.debug.preserve_context机制:调试控制台执行代码时恢复请求的上下文局部数据; - options header 中的名称统一小写(符合 RFC 6266);
AnyConverter构建 URL 时校验值; - 新增 sans-IO 的
is_resource_modified、parse_cookie、get_content_length; - 2.2.3(2023-02-14):multipart 部分数上限默认 1000,超出抛
RequestEntityTooLarge,缓解 DoS。
5.4 2.3(2023-04-25):性能与 header 重构
- Drop Python 3.7;
pyproject.toml取代setup.cfg; - **全面弃用"传 bytes 当字符串"**及大量
charset/errors参数——这是 Python 2 到 3 过渡的历史遗留,移除可省去大量实例检查与编码开销; werkzeug.urls模块弃用(保留uri_to_iri/iri_to_uri),改用urllib.parse;Authorization/WWWAuthenticate重构(:issue:1769、:pr:2619):两个类都有type/parameters/token属性(token支持 Bearer 这类单 token 方案);不再是 dict 但仍支持auth[key]、auth.key、auth.get、key in auth;都有from_header类方法(parse_authorization_header/parse_www_authenticate_header弃用);set_basic/set_digest弃用;可给response.www_authenticate赋实例列表以设置多个 header 值;parse_cookie/dump_cookie重构:性能提升最多 40%/60%;dump_cookie默认不再多余设置path="/";- 测试客户端 cookie 实现重构:弃用
cookie_jar,不再用http.cookiejar;发送请求 cookie 时做 domain/path 匹配(默认localhost与/);新增get_cookie方法;set_cookie/delete_cookie的首个位置参数server_name弃用,改用domain; Request.get_json()对非application/json抛 415(而非 400);- converter 的
part_isolating在其 regex 含/时默认False;自定义 converter 的 regex 可以含捕获组而不破坏路由; parse_options_header提速 2-3 倍并符合 RFC 9110;parse_accept_header按 RFC 9110 解析、丢弃非法q值;generate_password_hash支持 scrypt;PBKDF2 默认迭代升至 600,000;明文 hash 方法弃用,仅支持 scrypt 与 pbkdf2;- 开发服务器(明确标注不可用于生产)会排空请求流至 10GB 或 1000 次读取,使客户端能看到 413 而非 connection reset;丢弃含下划线的 header 键;URL 百分号编码必须始终表示 UTF-8 字节;
Request.charset/Response.charset/Client.charset弃用; max_content_length在访问流时立即检查、读取流时持续检查(:issue:1513)。
六、1.0 与 0.16:模块化清理的转折点
- 0.16.0(2019-09-19):弃用
werkzeug顶层的大多数属性,改为直接子模块导入(如from werkzeug.urls import url_quote),1.0 移除; - 1.0.0(2020-02-06):Drop Python 3.4;移除 0.15 中发出弃用警告的代码;移除大多数顶层属性;请求 cookie 解析为
MultiDict(同名 cookie 全保留,cookies[key]取第一个,getlist取全部);InternalServerError增加original_exception属性;Header 相等性比较忽略大小写;CSP header 通过Response.content_security_policy数据结构支持;LanguageAccept支持 "en" 与 "en-US" 回退匹配;MIMEAccept按 MIME 参数计算特异度;response.cache_control.immutable标志(浏览器支持仍实验性);429/503 异常支持retry_after参数;Map/Rule新增默认开启的merge_slashes;新增多个状态码(103、208、306、425、506、508、511);Headers增加update/setlist/setlistdefault;WebSocket 规则匹配与构建支持;SharedDataMiddleware默认fallback_mimetype改为application/octet-stream。
七、0.9~0.15:路由、测试客户端与调试器的成型期
这一阶段(2013-2019)塑造了 Werkzeug 至今的核心面貌:
- 0.9:
LimitedStream.tell支持;SSL 接口改进与证书自动生成;generate_password_hash支持任意 hashlib 算法;PBKDF2 支持;safe_join诞生;If-Range/Range/Content-Range 解析支持;HTTP 异常描述默认转义;CGIRootFix命名(原 LighttpdCGIRootFix); - 0.10:用标准库
ssl替代 OpenSSL;UUID converter;新增 504/505 异常;reloader 跟踪新增文件;PBKDF2 用 stdlib hmac 实现;MIMEAccept正确处理 mimetype 参数;Accept将 q=0 视为不可接受;MapAdapter.match区分/与空路径; - 0.11:调试器引入 PIN 认证(防止在生产环境误开调试器);
reloader_paths选项;许多自定义 cached_property 变为property子类;BuildError提供完整句子与建议;caches新增可选has方法; - 0.12:
response.age改为timedelta;cookie 超过默认 4093 字节抛异常(max_cookie_size属性与dump_cookie的max_size参数可配置);SharedDataMiddleware接受列表以保留查找顺序;开发服务器支持 chunked 请求; - 0.13:弃用 Python 2.6/3.3;
Authorization.qop为字符串(符合 RFC 2617); - 0.14:HTTP 异常被
Request.application自动捕获;SameSite cookie 属性支持;werkzeug.wsgi.ProxyMiddleware; - 0.15.0(2019-03-19):URL 构建提速约 7 倍(每个 Rule 编译自己的构建函数);
MapAdapter.build支持 MultiDict 多值;path_info默认/;RequestRedirect从 301 改为 308(保留动词与请求体);int/floatconverter 支持signed=True(如/jump/<int(signed=True):count>);Unauthorized增加www_authenticate参数;新增 424FailedDependency;parse_options_header理解 RFC 2231 参数续行;PBKDF2 迭代 150000;contrib 模块大规模弃用/迁移(LintMiddleware→werkzeug.middleware.lint、ProfilerMiddleware→werkzeug.middleware.profiler、ProxyFix→werkzeug.middleware.proxy_fix、cache 拆分为 cachelib、securecookie/sessions 拆分为 secure-cookie、atom 弃用、jsrouting/limiter/testtools 移除);ProxyFix重构(逐 header 配置信任的代理数,num_proxies弃用;新增X-Forwarded-Port/X-Forwarded-Prefix支持;原始环境值存于werkzeug.proxy_fix.orig);wsgi.get_host不再读X-Forwarded-For;测试客户端 redirect 处理重写(HEAD 不转 GET、307/308 保留方法与体、307 保留原方法);EnvironBuilder/Client支持json参数。
八、0.1~0.8:WSGI 工具集的奠基
早期版本确立了大量沿用至今的基础设施:
- 0.1(2007-12-09):初始发布(代号 Wictorinoxger);
- 0.2:
AnyConverter;securecookie;异常get_response();DispatcherMiddleware;cached_property(原名 lazy_property);dump_cookie/parse_cookie;import_string;BaseResponse.freeze;werkzeug.script; - 0.3:
Authorization/WWWAuthenticate;parse_list_header/parse_dict_header/parse_authorization_header/parse_www_authenticate_header;parse_form_data;MultiDict 家族抛BadRequest子类的特殊 KeyError;run_simple的use_debugger/use_evalex参数;"shallow" request 概念; - 0.4:
BaseResponse.make_conditional恒返回 self;CacheControl.no_cache/private行为调整;304 响应自动移除实体头;Headers支持切片与索引; - 0.5:
MIMEAccept/CharsetAccept;自研服务器替代 wsgiref;Client支持 cookie;is_hop_by_hop_header等函数;LimitedStream移入主包并默认抛异常;实验性 multipart 解析器;dump_options_header/parse_options_header;EnvironBuilder统一了create_environ/Client/from_values;secure_filename;passthrough_errors; - 0.6:
OrderedMultiDict;SSL 支持;MapAdapter.match的return_rule参数;FileStorage暴露 multipart 头;mimetype/mimetype_params属性;HEAD在含 GET 时隐式加入路由方法;BaseRequest.url_charset; - 0.7:host 匹配;
safe_join加入 security 模块;PATCH 方法(RFC 5789);If-Range/Range/Content-Range 解析支持;import_string错误信息改进;开发服务器默认解析出 URL 参数用于重定向; - 0.8:通用
BadRequestKeyError;_load_form_data文档化;自动设置 Content-Length;路由 server 名小写化;ProxyFix基于X-Forwarded-Proto更新wsgi.url_scheme;autocorrect_location_header/automatically_set_content_length控制开关;Headers禁止值内换行(防 header 注入);流式 URL 解码降低大表单内存占用。
九、贯穿始终的三大主线
通读全部版本后,可以提炼出三条清晰的技术主线:
- 安全优先:从 0.8 的 header 注入防护、0.11 的调试器 PIN、0.15 的 ProxyFix 安全默认值,到 3.x 系列密集的 GHSA 安全补丁(Windows 特殊设备名、multipart DoS、调试器主机白名单、SHA3-256 替代 SHA-1),安全始终是变更记录的高频主题;
- 类型注解与 API 收敛:从 2.0 的
py.typed、2.1 的内联注解,到 3.2.0 大规模弃用可变数据结构、统一from_header/to_header入口,Werkzeug 持续向"类型友好"演进; - sans-IO 架构:2.0 提取 sans-IO 基类 → 2.2 新增 sans-IO 解析函数 → 3.x 继续深化,为 ASGI 生态复用 Werkzeug 的 HTTP 语义铺路——当前仓库中 src/werkzeug/sansio 目录(含
http.py、request.py、response.py、multipart.py)正是这一路线的实体化成果,配套测试位于 tests/sansio。
十、如何把这份变更史用起来
- 升级前:从当前版本到目标版本逐段阅读,重点关注"移除先前已弃用的代码"与"行为变化"条目(如 3.2.0 的 redirect 302→303、3.1.0 的 max_form_memory_size 默认值);
- 排查行为差异:
Request.host校验、cache_control属性语义、测试客户端重定向规则这类"隐性行为变化"最容易在升级后引发问题,可对照 tests 下的test_wrappers.py、test_http.py、test_test.py、test_routing.py等验证预期行为; - 追踪安全修复:检索 CHANGES.rst 中的
:ghsa:引用,核对你的部署是否受影响的组件(multipart 解析、safe_join、调试器、开发服务器); - 把握 API 生命周期:某个 API 的"新增→弃用→移除"通常横跨 2-3 个版本,据此规划你的代码迁移窗口期。
综上,CHANGES.rst 不仅是一份发布日志,更是 Werkzeug 的设计决策史:它记录了为什么 redirect 默认 303、为什么 MultiDict 恒为不可变、为什么 ETag 改用 SHA3-256。对任何使用 Werkzeug(尤其是经由 Flask 间接使用)的开发者而言,这份文件都值得作为常备的升级参考手册。