Transmission 4.0.2 维护版本全解析：4.0.x 系列关键缺陷修复与源码级验证

Transmission 4.0.2 维护版本全解析：4.0.x 系列关键缺陷修复与源码级验证

【免费下载链接】transmissionOfficial Transmission BitTorrent client repository项目地址: https://gitcode.com/gh_mirrors/tr/transmission

Transmission 4.0.2 是继 4.0.0、4.0.1 之后的又一个"仅修复缺陷"（bugfix-only）版本，官方在 news/news-4.0.2.md 中总结了针对元数据解析、脚本环境变量、文件复制、网络协议、RPC 与各客户端的一批修复。阅读本文后，你将完整掌握 4.0.2 修复的全部缺陷清单及其影响面，并通过本仓库源码定位每一处修复对应的底层实现（如torrent-metainfo.cc、file-posix.cc、torrent.cc、file-piece-map.cc），从而准确评估升级收益、排查 4.0.x 遗留问题。

版本定位：4.0 系列的第二轮稳定性收口

4.0.2 延续了 4.0.1 的发布策略，是一次纯粹的缺陷修复版本，不引入任何新功能。这一策略意味着：Transmission 4.0 大版本（基于 C++ 重构的 libtransmission、新的 RPC 与 Web 客户端架构）在完成功能重构后，正通过密集的社区反馈（bug report、建议与补丁）对 4.0.x 系列进行稳定性收口。仓库中 news/news-4.0.1.md、news/news-4.0.2.md 同属这一节奏，而 4.0.2 主要针对4.0.0 引入的回归缺陷（约 10 项标注为 "Fixed 4.0.0 bug"）以及少量 4.0.1 的遗留问题。

对使用者而言，该版本的升级意义集中在四类场景：元数据兼容性（path.utf-8）、脚本钩子可靠性（TR_TIME_LOCALTIME）、存储/网络稳定性（CIFS 挂载下的文件复制、uTP 限速）以及多客户端体验（macOS watchdir、Web 快捷键等）。

四大重点修复速览

官方在 "Highlights" 中重点标注了四项修复，它们分别覆盖元数据误判、桌面端文件监控、限速失效与私种制作四个高感知场景：

其中"部分种子被误判为磁力链接"（PR #5025）直接关系到种子加载链路，属于 4.0.1 引入的高优先级回归；而 uTP 限速问题（PR #5086）则影响实际流量控制效果，与 libtransmission/peer-socket-utp.cc、libtransmission/bandwidth.cc 中带宽记账逻辑相关。

全平台修复深度解析

元数据解析与兼容性：path.utf-8键回归恢复

4.0.2 恢复了 torrent info 字典中path.utf-8键的支持（PR #3454）。这是 BEP 规范的兼容性字段：当文件路径含非 UTF-8 编码的原始字节时，种子可同时携带path（原始字节）与path.utf-8（UTF-8 版本）两套路径，客户端应优先采用 UTF-8 版本。源码中该键在 libtransmission/torrent-metainfo.cc 定义为：

static constexpr std::string_view PathUtf8Key = "path.utf-8"sv;

并在元数据解析时与path键并列处理：解析文件树时按pathStartsWith(InfoKey, FilesKey, ArrayKey, PathUtf8Key)识别（同文件 L174），遇到单个文件条目时在curdepth > 1的层级上同时接受PathKey与PathUtf8Key（L303）。仓库中还定义了配套的name.utf-8、publisher.utf-8、publisher-url.utf-8等键（L628、L639、L641），共同构成对 BEP 元数据 UTF-8 扩展的完整支持。该修复对从旧版本（如 2.x/3.00 时代生成的中文文件名种子）迁移来的用户尤其重要。

脚本钩子环境变量：TR_TIME_LOCALTIME取值修正

当种子完成下载并触发脚本钩子时，Transmission 会以环境变量的形式向脚本注入一批上下文信息（详见 docs/Scripts.md），其中就包括TR_TIME_LOCALTIME。4.0.2 修复了该变量的取值错误（PR #5006）。在 libtransmission/torrent.cc 的脚本调用实现中，可以看到它由当前时间格式化而来：

auto const localtime_str = fmt::format("{:%a %b %d %T %Y%n}", *std::localtime(&now)); // ... auto const env = std::map<std::string_view, std::string_view>{ { "TR_APP_VERSION"sv, SHORT_VERSION_STRING }, { "TR_TIME_LOCALTIME"sv, localtime_str }, { "TR_TORRENT_BYTES_DOWNLOADED"sv, bytes_downloaded_str }, // ... };

该环境变量会在 extras/send-email-when-torrent-done.sh 这类完成通知脚本中直接使用（例如拼接邮件正文中的完成时间）。因此，依赖该变量生成日志、邮件或文件名的时间戳类脚本，应随 4.0.2 一并验证取值是否符合预期。

文件 I/O：CIFS 挂载下的 2 GiB 复制块限制

4.0.2 将内核态文件复制（in-kernel copy）的单次复制块限制为 2 GiB（PR #5039），以避免 CIFS（SMB 挂载）下的大文件复制问题。实现位于 libtransmission/file-posix.cc：优先尝试 Linux 的copy_file_range(2)，并逐块循环复制，块大小取三者最小值：

size_t const chunk_size = std::min({ file_size, uint64_t{ SSIZE_MAX }, uint64_t{ INT32_MAX } }); auto const copied = copy_file_range(in, nullptr, out, nullptr, chunk_size, 0);

INT32_MAX即 2 GiB 上限（2147483647 字节）。当copy_file_range因跨文件系统返回EXDEV时，代码会回退到sendfile64（L305 起），再进一步回退到用户态复制，形成完整的多级回退链；相关能力在 libtransmission/CMakeLists.txt 中通过检测copy_file_range符号来启用（USE_COPY_FILE_RANGE）。对把下载目录或完成目录放在 NAS/CIFS 共享上的用户，该修复直接降低了复制大文件时的内核错误风险。

稳定性与崩溃类修复

4.0.2 集中修复了一批 4.0.0 引入的崩溃与断言问题：

• std::clamp()断言失败（PR #5080、#5203）：修复了某些输入下std::clamp的前置条件被违反导致的断言崩溃。
• 收到畸形 piece 数据时崩溃（PR #5097）：对等端返回的畸形数据不再触发 4.0.0 崩溃，这与 piece 数据校验链路（libtransmission/peer-msgs.cc）相关。
• 从 webseed 下载时潜在崩溃（PR #5161）：webseed（HTTP 种子）下载路径的崩溃风险被修复，涉及 libtransmission/webseed.cc。
• 文件首/尾 piece 优先级回归（PR #5167）：4.0.0 回归导致文件第一个和最后一个 piece 不再被提升下载优先级。这些边缘 piece 对"未下载完即可预览/播放"至关重要。源码依据在 libtransmission/file-piece-map.cc：

tr_priority_t tr_file_priorities::piece_priority(tr_piece_index_t const piece) const { // increase priority if a file begins or ends in this piece // because that makes life easier for code/users using at incomplete files. if (fpm_->is_edge_piece(piece)) { return TR_PRI_HIGH; } // ... }

• 对"包含所需 piece 的对等端"停止感兴趣（PR #5176）：修复了可能提前对有用对等端失去兴趣、导致下载停滞的逻辑问题。

网络协议与 tracker 交互

• 接收对等消息时的协议开销计算误差（PR #5091）：修正了统计协议开销（protocol overhead）时的小误差，影响上传/下载速率统计的准确性。
• tracker announce 响应中leechers参数处理改进（PR #5164）：更稳健地解析 tracker 返回的leechers字段，避免异常值影响对等端状态展示。
• IPv6 tracker URL 显示（PR #5174）：修复了 IPv6 形式 tracker 地址在界面上的显示问题（如http://[::1]:port/announce的方括号处理）。
• 规避旧版 libdht 的无效 peer 信息（PR #5218）：对旧版 libdht 的已知缺陷（可能提供无效对等端信息）做了 workaround，涉及 DHT 对等端来源 libtransmission/tr-dht.cc 的兼容层。

RPC 与 JSON 序列化

• JSON 生成时非 BMP 字符转义错误（PR #5096）：修复了生成 JSON 时对非基本多文种平面（non-BMP，如部分 emoji 与生僻汉字）字符的错误转义，保证通过 RPC/Web 接口传输的字符串可被正确解码。
• torrentGet.wanted返回值恢复 3.00 行为（PR #5170）：RPC 接口torrent-get的wanted字段恢复为与 3.00 一致的返回语义。在 libtransmission/rpcimpl.cc 中可以看到该字段的构造逻辑make_file_wanted_vec——按文件索引逐一取出tr_torrentFile(...).wanted组成布尔数组，并在torrent-get的字段分发处（L963-L964）按TR_KEY_wanted返回。第三方基于 RPC 开发的文件选择/管理工具应回归验证该字段。
• RPC 添加磁力链接的健全性检查改进（PR #5202）：通过 RPC 添加 magnet 链接时增加 sanity check，避免畸形链接进入会话。
• incomplete-dir 写入失败时的误导性错误信息（PR #5217）：当无法写入未完成目录时给出更准确的错误提示，便于定位权限或路径问题。

日志与杂项

• 日志中文件名信息简化（PR #5055）：日志输出更简洁，减少冗余路径信息。
• 4.0.2 同时是纯维护版本，未改变任何命令行参数或配置文件结构，已有 docs/Configuration-Files.md 中的配置项均可继续沿用。

客户端专项修复

macOS 客户端

• 修复一批轻微 UI 问题（布局、控件对齐，PR #5016、#5018、#5019、#5021、#5035、#5066）。
• 上传/下载徽标新增上/下箭头指示（PR #5095），方向信息更直观。
• 4.0.0 回归：删除并重启后旧种子重现（PR #5117）：修复了本地数据清理不彻底导致已删除种子复活的问题。
• 消除 macOS 端 "Unrecognized colorspace number -1" 错误消息刷屏（PR #5219）。
• 自定义目录添加新种子时本地数据找不到（PR #5060）：修复了在自定义文件夹场景下无法复用已存在数据的问题。
• 启动时copyWithZone()崩溃（PR #5079）。
• 修复 macOS 客户端的 watchdirs 失效问题（PR #5058，见重点修复）。

Qt 客户端

• 多文件种子"打开文件"改为打开种子所在文件夹（PR #5115），行为更符合直觉。
• 4.0.0 回归：无法一次性为多个种子批量添加 tracker（PR #5122）。
• 主窗口按种子显示的上传/下载比例修正（PR #5193）。

GTK 客户端

• 4.0.0 回归：忽略-m/--minimized命令行选项（PR #5175）：从命令行以最小化方式启动失效，现已恢复。
• 创建新种子时进度显示触发断言失败（PR #5180）。

Web 客户端

• 修复轻微 UI 问题（PR #5001）。
• 4.0.0 回归：备用速度（alternate speed）开始/结束时间设置无法保存（PR #5033）：涉及 libtransmission/session-alt-speeds.cc 对应的时间窗口配置。
• 桌面版 Safari 下快捷键失效（PR #5054）。
• 浅色与深色两种模式下的配色改进（PR #5083、#5114、#5151）。

命令行工具与守护进程

• Daemon：transmission-daemon的 "unrecognized argument" 错误消息可读性改进（PR #5029），更清晰地提示未知参数（可参考 daemon/daemon.cc 的参数解析入口）。
• transmission-remote：添加磁力链接时不再输出虚假错误信息（PR #5088），避免脚本在正常操作时误判失败。

工程与社区配套改进

• 文档更新（PR #4971、#4980、#5099、#5135、#5214、#5225）：涵盖构建依赖（如 Ubuntu 增加libssl-dev，见 docs/Building-Transmission.md）与使用说明的修订。
• 翻译更新（PR #5182）：同步更新各语言翻译，对应 po/ 目录下的.po文件。
• 交叉编译测试发现（PR #5197）：修复 4.0.1 在无模拟器交叉编译环境下无法发现测试的问题，涉及 tests/ 的 CMake 集成。

升级与验证建议

4.0.2 不引入配置迁移，升级路径平滑：

1. 从源码构建的用户按 docs/Building-Transmission.md 重新构建即可，版本号定义位于 libtransmission/version.h.in。
2. 构建后可通过transmission-daemon --version（或各客户端关于对话框）确认版本为 4.0.2。
3. 建议重点回归验证四类场景：加载含path.utf-8的旧种子、完成通知脚本中的TR_TIME_LOCALTIME、NAS/CIFS 目录下的大文件复制、以及 RPC 的torrent-get中wanted字段。
4. 若使用 Web 客户端备用速度定时切换，请确认开始/结束时间设置可保存（#5033 修复项）。

致谢与后续版本

4.0.2 的修复离不开社区的反馈与贡献：包括恢复path.utf-8支持的 Colin B.（@Lanzaa）、修正TR_TIME_LOCALTIME的 @wiz78、改进leechers处理与 RPCwanted语义的 @reardonia、修复 JSON 转义的 Daniel Kamil Kozar（@xavery）等；macOS/Web/Daemon 等各端亦有 @nevack、@GaryElshaw、@dareiff、@tessus 等人的评审与修复。翻译与文档贡献来自 @ile6695、@maxz、@midzer、@tearfur、@trim21 等。官方也持续呼吁翻译志愿者参与，详见 docs/Translating.md。后续 4.0.x 与 5.0 的开发进展可关注 news/ 目录下的版本说明（如 news/news-5.0.0-draft.md）。

【免费下载链接】transmissionOfficial Transmission BitTorrent client repository项目地址: https://gitcode.com/gh_mirrors/tr/transmission