@erdai/vite-plugin-sourcemap-upload

用于在 Vite 构建后自动将产物中的 .map 文件上传到指定服务器的插件。
支持并发上传、单文件重试、指数退避 + 抖动、可中止（响应进程信号），并在上传成功后可选删除本地 sourcemap 文件。

徽章与简介

• 支持 ESM / CommonJS 发布
• 使用 multipart/form-data 上传（FormData + axios）
• 可以在 CI / 本地构建中使用

安装

# npm
npm install @erdai/vite-plugin-upload-sourcemap -D

# pnpm
pnpm add -D @erdai/vite-plugin-upload-sourcemap

快速使用（最简示例）

import { defineConfig } from 'vite';
import uploadSourcemap from '@erdai/vite-plugin-upload-sourcemap';

export default defineConfig({
    // ...你的其他vite配置...
    plugins: [
        uploadSourcemap({
            uploadUrl: 'https://your-upload-url.example.com/upload',
            enable: process.env.NODE_ENV === 'production'
        })
    ],
    build: {
        sourcemap: 'hidden' // 推荐：生成 sourcemap 但不暴露至最终资源
    }
});

完整选项说明（IOptions）

• uploadUrl: string （必填）
  上传接口地址，插件会以 multipart/form-data 的 file 字段 POST 上传每个 .map 文件。
• enable?: boolean = false
  是否启用插件（可基于环境变量动态控制）。
• concurrency?: number = 4
  并发上传数量（同时进行的上传任务数）。
• retry?: number = 1
  每个文件的额外重试次数（不含第一次尝试）。例如 1 表示总共最多尝试 2 次。
• removeUploaded?: boolean = true
  上传成功后是否删除本地 sourcemap 文件。
• verbose?: boolean = false
  是否输出详细日志，便于调试上传过程。

行为细节与注意事项

• 上传协议
  • 使用 multipart/form-data，字段名固定为 file，上传文件名为文件 basename（例如 bundle.js.map）。
  • 后端应对 2xx 状态视为成功，非 2xx 将触发重试逻辑（retry + calcBackoff）。
  • 若后端要求鉴权（Token、Cookie 等），目前插件不直接支持自定义 headers；可在前置代理或自行改造插件以传 headers。
• 可取消行为（中断处理）
  • 插件在上传阶段创建 AbortController，并监听 SIGINT / SIGTERM（Ctrl+C / 进程终止）。
  • sleep 重试期间会响应 AbortSignal 并立即取消等待。
  • axios 请求会将 signal 传入（axios 1.x + Node 16+ 支持），以尝试中止正在进行的请求。
  • 中止后，未完成的上传会返回失败结果并不会阻塞构建进程。
  • 避免在构建被手动中断或 CI 超时时，上传任务挂起过久。
• 重试与退避
  • 使用指数退避（base=500ms）并加入 ±30% 随机抖动以避免集群同时重试（thundering herd）。
  • calcBackoff(attempt) 返回毫秒数，可传入 sleepWithAbort 使用。

常见问题（FAQ）

• Q: 为什么 myfile.js.map 没上传？
  A: 检查 build 是否真的生成了 .map 文件、outDir 是否正确、插件是否启用（enable）、以及 uploadUrl 是否有效。
• Q: 我想在上传时携带 token / headers，怎么做？
  A: 当前插件默认不支持自定义 headers。可扩展插件源码将 headers 传给 axios，或在后端做代理以接收公共 uploadUrl。

许可证

• ISC