Vue / 系统课时
文件上传与下载
文件上传与下载
文件功能看似只是“选一个文件再传上去”,实际还要处理前置校验、上传进度、失败重试、重复请求和二进制下载。下面用 Vue 3 + TypeScript 做一套可直接迁入业务组件的最小闭环。
学习目标
- 在上传前限制 MIME 类型与文件大小,并给出明确错误。
- 使用可观察进度的上传请求,并保留失败后的重试上下文。
- 正确把下载响应转换为 Blob 文件流并释放浏览器资源。
把文件操作拆成两条数据流
上传链路包含选择文件、前端校验、发送字节、进度事件、服务端落盘与成功或失败状态;下载链路则从文件 ID 请求二进制响应,再由浏览器创建临时 URL 并触发保存。两条链路共享“文件元数据”,但状态与错误处理应彼此独立。

前端校验负责尽早反馈,服务端仍必须再次检查类型、大小和权限。失败重试还要考虑“服务端其实已收到文件,但客户端没收到成功响应”的模糊状态,因此企业接口最好支持幂等键。
实现上传进度、重试与下载
示例约定 POST /api/files 接收字段名为 file 的 multipart/form-data,返回 { id, name };服务端同时识别 X-Upload-Idempotency-Key。GET /api/files/:id 返回文件二进制内容。
<template>
<section>
<input
type="file"
accept="image/png,image/jpeg,application/pdf"
:disabled="status === 'uploading'"
@change="onSelect"
/>
<p v-if="error">{{ error }}</p>
<progress v-if="status === 'uploading'" :value="progress" max="100" />
<p v-if="status === 'uploading'">上传进度:{{ progress }}%</p>
<button
:disabled="!selectedFile || status !== 'idle'"
@click="upload"
>
上传
</button>
<button v-if="status === 'error'" @click="retry">重试</button>
<button v-if="uploaded" @click="download">下载 {{ uploaded.name }}</button>
</section>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type UploadedFile = { id: string; name: string }
type UploadStatus = 'idle' | 'uploading' | 'success' | 'error'
const allowedTypes = new Set([
'image/png',
'image/jpeg',
'application/pdf',
])
const maxSize = 10 * 1024 * 1024
const selectedFile = ref<File | null>(null)
const uploaded = ref<UploadedFile | null>(null)
const status = ref<UploadStatus>('idle')
const progress = ref(0)
const error = ref('')
let idempotencyKey = ''
function isUploadedFile(value: unknown): value is UploadedFile {
if (!value || typeof value !== 'object') return false
const file = value as Record<string, unknown>
return typeof file.id === 'string' && typeof file.name === 'string'
}
function onSelect(event: Event): void {
const input = event.target as HTMLInputElement
const file = input.files?.[0] ?? null
selectedFile.value = null
uploaded.value = null
status.value = 'idle'
progress.value = 0
error.value = ''
if (!file) return
if (!allowedTypes.has(file.type)) {
error.value = '仅支持 PNG、JPEG 或 PDF'
return
}
if (file.size > maxSize) {
error.value = '文件不能超过 10 MB'
return
}
selectedFile.value = file
// 同一次选择后的所有重试复用同一个键,前提是服务端按该键做幂等处理。
idempotencyKey = crypto.randomUUID()
}
function uploadWithProgress(
file: File,
onProgress: (value: number) => void,
): Promise<UploadedFile> {
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest()
xhr.open('POST', '/api/files')
xhr.responseType = 'json'
xhr.setRequestHeader('X-Upload-Idempotency-Key', idempotencyKey)
xhr.upload.onprogress = (event) => {
if (event.lengthComputable) {
onProgress(Math.round((event.loaded / event.total) * 100))
}
}
xhr.onerror = () => reject(new Error('网络错误,上传未完成'))
xhr.onload = () => {
if (xhr.status < 200 || xhr.status >= 300) {
reject(new Error(`上传失败:${xhr.status}`))
return
}
if (!isUploadedFile(xhr.response)) {
reject(new Error('上传响应格式不正确'))
return
}
resolve(xhr.response)
}
const formData = new FormData()
formData.append('file', file)
xhr.send(formData)
})
}
async function upload(): Promise<void> {
if (!selectedFile.value || status.value === 'uploading') return
status.value = 'uploading'
progress.value = 0
error.value = ''
try {
uploaded.value = await uploadWithProgress(
selectedFile.value,
(value) => (progress.value = value),
)
progress.value = 100
status.value = 'success'
} catch (cause) {
status.value = 'error'
error.value = cause instanceof Error ? cause.message : '上传失败'
}
}
async function retry(): Promise<void> {
if (status.value === 'error') await upload()
}
async function download(): Promise<void> {
if (!uploaded.value) return
error.value = ''
try {
const response = await fetch(
`/api/files/${encodeURIComponent(uploaded.value.id)}`,
)
if (!response.ok) throw new Error(`下载失败:${response.status}`)
const blob = await response.blob()
const url = URL.createObjectURL(blob)
const anchor = document.createElement('a')
anchor.href = url
anchor.download = uploaded.value.name
document.body.appendChild(anchor)
anchor.click()
anchor.remove()
// 等浏览器接管下载后再释放临时 URL。
setTimeout(() => URL.revokeObjectURL(url), 1000)
} catch (cause) {
error.value = cause instanceof Error ? cause.message : '下载失败'
}
}
</script>预期结果
选择 PNG、JPEG 或 PDF 且不超过 10 MB:允许点击“上传”。
选择其他类型或超过 10 MB:立即显示错误,不发送上传请求。
上传中:progress 随浏览器 upload progress 事件更新,并阻止重复上传。
上传失败:保留原 File 与同一个幂等键,点击“重试”可再次发送。
上传成功:显示下载按钮;点击后按服务器返回的文件 ID 获取二进制并触发浏览器保存。实际上传速度、文件 ID、HTTP 状态码和下载路径会随网络与服务端环境不同而变化。
为什么这里使用 XMLHttpRequest
浏览器原生 fetch 适合普通请求和下载流,但目前没有通用的上传进度事件 API;XMLHttpRequest.upload.onprogress 仍是实现上传百分比反馈的直接方案。若项目已统一使用 Axios,也可以使用其浏览器端上传进度能力,状态设计不需要改变。
进度条只表示“浏览器已发送多少字节”,不等于服务端已经完成病毒扫描、转码或持久化。大型文件系统应把“上传完成”和“后处理完成”拆成两个业务状态,而不是在 100% 时直接宣布所有处理成功。
重试与安全边界
客户端的 accept、MIME 检查和大小限制都只能改善体验,不能作为安全边界。服务端必须重新验证文件头、真实类型、大小、访问权限和存储路径,并对恶意文件执行符合业务要求的扫描策略。
下载完成后要调用 URL.revokeObjectURL 释放临时对象 URL;如果长期创建 Blob URL 而不回收,单页应用在大文件或高频下载场景中会积累不必要的内存占用。