Motrix 2.0.0-beta.23 技术解读：HTTP/FTP 文件修改时间选项与桌面启动、托盘行为的平台化重构

本文基于 docs/release-notes/2.0.0-beta.23.zh-CN.md 编写，是一篇面向下载工具研发与深度用户的预发布版本技术解析。全文围绕“下载文件的修改时间控制”“外观设置中启动文案与系统托盘的平台化调整”“Settings 控件布局统一”“Windows 新建任务窗口高度折叠修复”四条主线展开，同时对照当前仓库源码（engine-settings 校验、aria2 参数生成、托盘实现 等）逐项印证设计意图与底层实现，并完整给出本 beta 的发布门禁产物矩阵与各分发渠道限制。

Motrix 2.0.0-beta.23 是一次以“跨平台行为收敛”为主题的预发布迭代：它让 HTTP/FTP 下载完成后可以由用户决定文件使用“本地完成时刻”还是“服务器 Last-Modified 时刻”作为修改时间；同时把启动方式、托盘常驻与单击行为按 macOS / Windows / Linux 各自的操作系统惯例重新收敛，统一并收紧 Settings 控件布局，并修复了 Windows 上新建任务窗口无法缩回紧凑高度的问题。读完本文，你将掌握这些改动对应的设置入口、aria2 底层参数（--remote-time）、完整的“发布门禁通过后”分发矩阵，以及如何在测试前与测试中规避预发布数据风险。

需要说明的是，本文档对应 v2.0.0-beta.23 时间点的发布说明，而当前工作区开发主线已推进到更晚的 beta 版本（package.json 中版本为 2.0.0-beta.33）；下文描述的选项、源码路径与行为在现有仓库中仍然可查，作为对该 beta 发布内容的源码级佐证。

---

一、版本定位与总体目标

本小节根据 2.0.0-beta.23.zh-CN.md 开篇归纳 beta.23 的核心目标：

• 新增下载文件修改时间选项：HTTP 与 FTP 任务完成后，可在“本地修改时间”与“服务器修改时间”之间选择；
• 启动与托盘行为平台化：使启动、托盘常驻与托盘单击行为更符合各桌面操作系统习惯；
• Settings 布局收敛：统一并收紧短数字输入框与紧凑选择器的宽度、重组速度限制的重置操作；
• 修复 Windows 新建任务窗口高度问题：解决折叠后无法恢复紧凑高度的缺陷。

需要注意的是，该版本只有在全部受保护发布门禁通过后才会进入公开分发。这是 Motrix 2.x 预发布流水线的一贯做法：版本产物先由发布门禁（容器门禁、Snap source validation、AppImage/Flatpak 专项验证等）把关，再决定是否公开。因此文档中所有产物均以“计划/条件达成后”为前提。

---

二、核心特性一：下载文件修改时间选项（HTTP/FTP）

2.1 功能语义

beta.23 为 HTTP 与 FTP 下载引入了**完成后文件修改时间（modification time）**的可选控制，对应 GitHub 上游 issue #1542 的需求。两个取值的含义分别为：

选项	语义	行为
本地修改时间（Local）	默认选项	文件修改时间保留“下载完成”的时刻
服务器修改时间（Server）	可选	当服务器响应提供 Last-Modified 头时，把该远程时间戳应用到本地文件

“本地修改时间”之所以是默认值，是因为它最能贴近用户直觉——下载完成即代表文件“最新”；而“服务器修改时间”适合需要与源站内容保持一致、或需要精确还原源文件时间语义的场景（例如镜像站、离线归档）。需要强调的一个边界是：Server 模式只有在服务器提供 Last-Modified 时才生效，若响应头缺失，则无法应用远程时间戳（此时的表现与本地模式一致）。

2.2 源码级实现印证

这一能力在底层是交给 aria2 完成的：aria2 原生提供了 --remote-time 开关，用于在下载完成后将文件的修改时间设置为服务器的 Last-Modified 时间（若有）。

• 设置项的持久化与默认值：引擎设置 schema 中定义了 remoteTime 布尔字段，默认值为 false（即默认使用本地修改时间）。对应测试见 engine-settings.test.ts：

describe('engineSettingsSchema remoteTime', () => {
  it('uses the local modification time by default', () => {
    expect(DEFAULT_ENGINE_SETTINGS.remoteTime).toBe(false)
  })

  it.each([true, false])('accepts %s', (remoteTime) => {
    expect(engineSettingsSchema.parse({ remoteTime }).remoteTime).toBe(remoteTime)
  })

  it.each(['server', 1, null])(
    'recovers invalid persisted value %s to false',
    (bad) => {
      expect(engineSettingsSchema.parse({ remoteTime: bad }).remoteTime).toBe(false)
    }
  )
})

从该测试还可以读出两个工程细节：schema 对布尔字段做了宽松解析与自动纠错——历史设置文件中如果残留 'server'、数字 1 等非布尔值，会被恢复为默认的 false，避免脏数据破坏应用启动。

• 转换为 aria2 命令行参数：引擎启动时会把 remoteTime 序列化为 aria2 的 --remote-time 参数。aria2-config-builder.ts 中直接拼装：

`--remote-time=${settings.remoteTime}`,

对应的参数映射关系同样出现在 engine-supervisor.ts：

remoteTime: 'remote-time',

而 aria2-config-builder.test.ts 验证了两种取值分别产出 --remote-time=false 与 --remote-time=true 的完整命令参数序列。

• 设置界面入口：该选项位于“下载设置（Downloads）”面板中，控件名为“文件修改时间”，下拉选项为“本地修改时间 / 服务器修改时间”。渲染组件见 downloads-form.ts，其交互测试见 downloads-dialog.test.tsx（选择 Server 后提交即调用 UpdateSettings 并携带 engine: { remoteTime: true }）。

2.3 验证步骤

文档给出了一套可复现的手工验证流程：

1. 准备一个会返回 Last-Modified 响应头的 HTTP 或 FTP 资源；
2. 在“下载设置”中先把文件修改时间选为本地修改时间，完成一次下载，记录本地文件的修改时间；
3. 再把该选项切换为服务器修改时间，再次下载同一资源；
4. 对比两次产物的修改时间：本地模式下应等于下载完成时刻；服务器模式下应等于服务器声明的 Last-Modified 时间。

同时建议在测试时确认外观设置中的启动方式与托盘单击行为符合当前桌面环境（见下文第三、四节）。

---

三、核心特性二：启动方式文案与行为的平台化

3.1 为什么要“平台化”

不同桌面操作系统对“应用启动后去哪里”有着截然不同的习惯：

• macOS：用户习惯程序坞（Dock）与菜单栏（Menu Bar）的组合存在感；
• Windows / Linux：主流惯例是启动后打开主窗口，或最小化到系统托盘常驻；
• Linux 的托盘能力高度依赖桌面环境（GNOME 的 AppIndicator、KDE 的 System Tray 等），并非所有发行版默认支持。

beta.23 因此把“外观设置”中的启动相关文案按平台拆分，避免用一个跨平台的模糊措辞误导用户：macOS 侧提供“程序坞 + 菜单栏”的组合描述；Windows 与 Linux 侧则说明可选择“打开主窗口”或“在系统托盘中启动”，其中 Linux 文案还会明确提示“托盘支持取决于当前桌面环境”。从当前仓库结构看，桌面窗口启动计划与托盘能力确实分平台建模，相关测试见 window-startup-plan.test.ts、tray.test.ts 与 tray-icon.test.ts。

3.2 托盘入口的“兜底”策略

文档强调了一个易被忽略的健壮性改动：

• Windows 与 Linux 始终保留托盘入口，作为“重新打开 Motrix”的可靠途径；
• 即使旧设置文件中包含仅 macOS 支持的“隐藏托盘”值，Windows/Linux 也不会因此失去托盘入口——设置迁移过程中若遇到跨平台不兼容字段，系统会按平台能力兜底，而不是把不可达状态原样带入新平台；
• Linux 单击托盘现在会切换主窗口（显示/隐藏），而右键菜单等行为只使用 Electron 在对应操作系统上实际支持的托盘菜单事件，避免把 macOS 专属事件假设强加到其他平台。

这些细节共同说明：beta.23 的托盘改动不仅是 UI 文案层面，还包括事件模型与设置迁移的兼容性兜底。相关实现可进一步阅读 tray.ts 与 tray-icon.ts。

---

四、核心特性三：Settings 控件布局统一与速度限制重置语义

4.1 布局一致性

Settings 面板中的短数字输入框（如各类限速数值输入）与紧凑选择器（如“文件修改时间”下拉框）采用了更一致的宽度规则。从渲染测试可以印证这一点：修改时间选择器被断言应用了 min-w-30、max-w-64 而非固定 w-30，即控件可以根据国际化文案长度自适应伸缩（例如中文“本地修改时间”比英文 “local” 更长），从而在收紧布局的同时避免文案被截断。见 downloads-dialog.test.tsx。

4.2 速度限制重置操作的语义拆分

速度限制（Speed Limit）区域的重置操作被调整到数值输入框前方，并明确了两种不同的重置语义：

• 常规上限（即“整体/常规速度限制”）下的重置，显示为“不限速”——语义是取消该常规上限的约束；
• 低速上限（如“低速时段限速”这类次级限制）下的重置，显示为“沿用常规上限”——语义是让低速限制回落继承常规上限，而非简单地清零。

这种“区分常规上限与低速继承上限”的重置文案，本质上是把两种语义截然不同的操作从“共用一个 Reset 按钮”中拆开，避免用户误解。渲染测试中亦有对“speed modes with user-facing names”的断言（见 downloads-dialog.test.tsx 起的用例）。

---

五、核心特性四：Windows 新建任务窗口高度折叠修复

新建任务窗口是一个不可调整大小（non-resizable）的窗口。beta.23 之前，在 Windows 上把窗口折叠到紧凑高度后，无法再恢复，对应 GitHub 上游 issue #1879。

本次修复的核心手段是：折叠/还原不再依赖简单的 size 设置，而是改用“保留当前位置”的 bounds 边界更新来缩小窗口。即：

• 窗口缩小时保持其当前屏幕位置不动，只更新尺寸边界；
• 该改动修复了 Windows 上折叠后无法恢复紧凑高度的回归；
• 同时保留了 macOS 原有的动画行为——即修复按平台收敛，不在修复 Windows 的同时破坏 macOS 的既有体验。

这与本版本“平台化收敛”的主题一脉相承：同一个视觉行为（窗口折叠），不同平台的窗口管理差异导致需要不同的实现路径。涉及窗口启动与尺寸策略的实现可参考 window-startup-plan.ts 对应的源码模块。

---

六、测试前须知：预发布数据安全

beta.23 是预发布软件，文档明确给出以下风险边界与测试建议：

1. 安装前备份现有 Motrix 应用数据与下载文件；
2. v1 数据迁移未经验证：Motrix v1 数据的迁移路径尚未经过验证，不要让本 beta 使用你唯一一份 v1 数据；
3. 并行测试优先：条件允许时，建议通过独立的系统账户、独立设备或 Docker 数据目录并行测试 v2，不要把重要下载文件的唯一副本寄托在本 beta 上。

这些提醒对应 2.x 预发布流水线的一贯策略：数据格式、迁移器与存储布局仍在迭代中，任何 beta 都应按“可丢弃的测试环境”来对待。

---

七、发布门禁通过后的计划下载项（分发矩阵）

文档给出了 beta.23 在全部发布门禁通过后的计划产物矩阵，完整如下：

分发方式	架构	计划产物
macOS 12 或更高版本	arm64（Apple Silicon）、x64（Intel）	DMG 与 ZIP
Windows	x64	未签名 NSIS 安装包（.exe）与 ZIP
Linux	x64、arm64	AppImage、DEB 与 RPM
Flatpak Native Host companion	linux/x64、linux/arm64	Motrix-Native-Host-2.0.0-beta.23-linux-<arch>.tar.gz
Docker Hub / GHCR	linux/amd64、linux/arm64	两个 registry 中不可变的 2.0.0-beta.23 tag
Snap Store	—	本 beta 不发布

容器镜像：当全部容器门禁通过后，带版本的镜像引用将是：

• docker.io/motrixapp/motrix-server:2.0.0-beta.23
• ghcr.io/agalwood/motrix-server:2.0.0-beta.23

存储、网络与升级的详细说明见仓库内的 Docker Server 部署指南。需要注意：Beta 容器 tag 是不可变的，且不会更新 latest、stable 或其他稳定版浮动 tag——这意味着你在 CI/CD 或 compose 中引用的 2.0.0-beta.23 指向的内容一经发布便不再变化，适合做可复现性测试。

---

八、各分发渠道的限制与注意事项

文档在“分发说明”一节对每个渠道给出了明确的边界，逐条解读如下：

• AppImage（Linux）：桌面集成需要用户主动选择启用，并且只写入当前用户的 XDG 数据目录；AppImage 内的 Native Messaging host 在挂载镜像外没有稳定路径，因此浏览器扩展暂时还不能把下载任务移交给 AppImage 版本（即扩展桥接能力对该渠道不可用）。
• Flatpak：会单独验证，不随该版本的 release tag 发布；GitHub 预发布版中会包含对应的 Native Host companion 压缩包（即上一节表格中的 tar.gz）。
• Windows 架构范围：不提供 Windows arm64 与任何 32 位安装包，仅提供 x64。
• Windows 签名状态：安装包未签名，可能触发 Windows SmartScreen 警告；官方建议仅在官方 GitHub 预发布正式发布后再下载，降低供应链风险。
• Snap：本 beta 不发布。预发布的 Snap 流水线运行会在 source validation 之后停止，不会构建 Snap 产物、不会上传 Store revision，也不会改动 latest/edge 通道。

这些渠道差异（谁先发、谁后发、谁不签名、谁不更新浮动 tag）本质上反映的是 Motrix 2.x 发布体系对“发布门禁”的分级控制：越晚合入正式分发渠道的产物，越要经过独立验证。

---

九、反馈渠道与可复现问题报告

文档建议通过 GitHub Issues 报告可复现问题，并附上以下最小复现信息，以便维护者定位：

• 操作系统；
• CPU 架构（arm64 / x64 等）；
• 安装包类型（DMG / NSIS / AppImage / DEB / RPM / 容器 / Flatpak 等）；
• 完整复现步骤。

结合本文第二～五节的验证步骤（文件修改时间对比测试、启动方式与托盘行为核对、速度限制重置语义、Windows 窗口折叠还原），即可对 beta.23 的四大改动逐项回归。

---

结语

Motrix 2.0.0-beta.23 表面上看是一个“小步快跑”的预发布迭代，但其技术含量集中在跨平台行为的收敛与底层参数/设置 schema 的健壮性上：--remote-time 的默认关闭策略与 schema 纠错保证了老配置文件的平滑兼容；托盘“兜底常驻 + 按平台使用事件模型”避免了 Windows/Linux 用户被 macOS 专属设置“坑”到失去退出入口；Settings 布局的一致性让国际化文案在收紧的控件中仍然可读；而 Windows 窗口折叠修复则示范了“按平台分路径实现同一视觉行为”的正确姿势。若你要在自己的桌面应用里做类似的多平台收敛，这些取舍与实现路径（aria2-config-builder.ts、engine-supervisor.ts、engine-settings 校验、tray.ts、downloads-form.ts）都是可以直接对照阅读的样例。