tus 协议

tus 是一个基于 HTTP 的可恢复上传开放协议，定义断点续传的前后端协作规则

#type / concept #status / evergreen #tech / dev / frontend #tech / dev / backend #protocol / http

[!info] related notes

所属 MOC: 前端工程化 MOC

前置概念: 断点续传机制, HTTP

并列概念: Uppy

关系笔记: 大文件传输系统设计

tus 协议

一句话定义

tus 是一个基于 HTTP 的可恢复上传开放协议，定义了前后端如何协作实现断点续传，是一个行业标准而非具体库。

核心内容

是什么

tus（Transfer Upload System）是一个开放协议，目标是让上传在中断后还能继续，不需要从头重新传。它定义了：

怎么创建一个上传任务
怎么知道已经传了多少字节
中断后怎么继续
客户端和服务端如何通过 HTTP 头和状态码协作

协议核心机制

创建上传：POST 或 PATCH 请求创建上传任务，获取上传 URL
上传数据：通过 PATCH 请求上传数据，使用 Content-Length 和 Upload-Offset 头
查询状态：HEAD 请求获取已上传字节数
恢复上传：根据 Upload-Offset 从断点继续

关键 HTTP 头

头字段	作用
`Upload-Length`	文件总大小
`Upload-Offset`	当前已上传偏移量
`Upload-Metadata`	文件元数据（文件名、类型等）
`Tus-Resumable`	tus 协议版本

官方实现

tus-js-client：JavaScript 客户端，支持浏览器、Node.js、React Native
tusd：Go 语言参考服务端实现
tus-java-client：Java 客户端
各语言社区实现

适用场景

需要严格的断点续传能力
需要前后端统一的上传协议标准
需要多端（Web、移动端、桌面端）统一续传机制
大文件上传的生产环境

边界与易混淆点

tus ≠ 前端组件：它是协议标准，不是 UI 库
tus ≠ 专有技术：它是开放协议，任何人都可以实现
tus 可以单独使用：不用 Uppy，直接用 tus-js-client 也能实现断点续传
tus 和 Uppy 的关系：Uppy 可以使用 tus 作为底层传输协议，但 Uppy 也可以用其他协议