vite-plugin-cos-uploading

一个可以将打包好的资源文件上传到腾讯云 COS，并把代码中资源引用替换为 CDN 地址的 Vite 插件。支持自定义参数处理

特性

• 🚀 打包完成后自动上传资源文件到腾讯云 COS
• 🔁 自动重写构建产物中的资源引用为 CDN 地址
• ✏️ 支持通过 rewriteQueryString 自定义（新增 / 改写 / 去除）资源引用的 querystring
• ⚡ 并发上传（可配置），支持大文件批量场景
• 🧪 支持 test 模式预演，不真正上传
• 🗑️ 可选删除本地原文件与空目录
• 🔐 支持从环境变量读取凭据，避免硬编码

安装

npm i vite-plugin-cos-uploading -D
# 或
pnpm add vite-plugin-cos-uploading -D

要求 Node.js >= 18。

配置参数

必填

| 参数 | 说明 | | --- | --- | | secretId | 腾讯云授权 SecretId（可从「访问管理 → API 密钥管理」获取） | | secretKey | 腾讯云授权 SecretKey | | bucket | 上传到哪个存储桶，格式为 <bucketname>-<appid>，如 examplebucket-1250000000 | | region | 存储桶所在地域，如 ap-guangzhou（COS 每个请求都需要带上地域，故为必填） |

可选

| 参数 | 说明 | 默认值 | | --- | --- | --- | | cdnHost | 上传后用于替换的资源文件 CDN 域名，留空则跳过 CDN 重写 | '' | | from | glob 字符串，指定要上传的文件 | ./dist/assets/** | | dist | 上传到 COS 的目录前缀 | ''（根目录） | | timeout | COS 单次请求超时（毫秒），映射为 SDK 的 Timeout | 30000 | | overwrite | 是否覆盖 COS 同名文件（关闭时通过 headObject 检查存在性，已存在则跳过） | true | | verbose | 是否打印上传日志 | true | | test | 测试模式：只打印不真正上传 | false | | deleteOrigin | 上传后是否删除本地原文件 | false | | deleteEmptyDir | 目录清空后是否删除空目录（需 deleteOrigin: true） | false | | quitWpOnError | 出错时是否中断打包 | false | | version | 版本号，配合 setVersion 使用 | '' | | setVersion | 上传成功后的回调（一般用于上报版本号） | — | | fileSuffix | 需要上传的资源后缀 | ['jpg','jpeg','png','gif','svg','webp','ico','bmp','webm','avi','mp4','mp3','flv','mov'] | | assetsDirectory | 资源目录名，用于 CDN 路径替换 | assets | | outputDirectory | 打包输出目录 | dist | | setCosPath | 自定义 COS 对象键生成函数 | 以 outputDirectory 为基准的相对路径 | | rewriteQueryString | 改写资源引用的 querystring，签名 (path, query) => string。path 为 CDN 替换前的原始资源路径；query 入参与返回值都包含 ?（如 ?v=1），无查询串时为 ''；返回值不以 ? 开头时会自动补齐 ?，返回 '' 表示去掉查询串 | — | | concurrency | 并发上传数 | 5 | | endpoint | 自定义请求域名（映射为 COS SDK 的 Domain），可用于内网域名或 CDN 源站域名。传入后覆盖 SDK 默认按 Bucket/Region 拼接出的域名 | — | | secure | 是否使用 HTTPS（true）/ HTTP（false）。映射为 SDK 的 Protocol（https: / http:）。不传时使用 SDK 默认（https） | — |

内网自动探测

当未显式配置 endpoint（Domain）且未显式配置 secure（Protocol） 时，插件会在 configResolved 阶段通过 TCP 端口探测判断当前是否处于腾讯云内网环境（探测 cos-internal.<region>.myqcloud.com 的 80 端口）：

• 探测命中（内网）：自动切换为内网 Domain，并使用 HTTP（Protocol: 'http:'），提升上传速度、避免公网带宽。
• 探测失败 / 超时：视为非内网，沿用用户原有配置（region + 默认 HTTPS），不会中断构建。

该机制对 CI、无外网等环境安全：任何探测异常都静默回退，不抛错。 若需完全跳过自动探测，显式设置 endpoint 或 secure 即可。

改写资源引用的 querystring

rewriteQueryString 允许你在 CDN 路径替换时，自定义资源引用后面的 querystring（例如统一打版本号、缓存破坏标识等）。

rewriteQueryString?: (path: string, query: string) => string

• path：CDN 替换前的原始资源路径，如 /assets/logo.png，仅用于识别资源；
• query：原 querystring，包含前导 ?（如 ?v=1）；若原引用没有查询串则为 ''；
• 返回值：作为新的 querystring 拼接到 CDN 地址之后 —— 以 ? 开头时直接使用（如 ?v=2），不以 ? 开头时会自动补齐 ?（如 v=2 → ?v=2）；返回 '' 则去掉查询串。

不配置 rewriteQueryString 时，保持原 querystring 不变。

示例：

cosUploadPlugin({
  cdnHost: 'https://cdn.xxx.com',
  // ...其它配置
  // 统一把所有资源引用的查询串替换为构建版本号（带不带 `?` 都行）
  rewriteQueryString: (_path, _query) => `?v=${process.env.BUILD_VERSION}`,
})

转换效果：

| 原引用 | rewriteQueryString 返回值 | 替换后 | | --- | --- | --- | | /assets/logo.png?v=1 | ?v=2 | https://cdn.xxx.com/static/assets/logo.png?v=2 | | /assets/logo.png | cache=bust | https://cdn.xxx.com/static/assets/logo.png?cache=bust | | /assets/logo.png?v=1 | '' | https://cdn.xxx.com/static/assets/logo.png |

⚠️ 安全提醒：secretId / secretKey 非常敏感，请通过环境变量读取，切勿硬编码到提交到仓库的配置文件中。

使用示例

// vite.config.js
import { defineConfig } from 'vite'
import cosUploadPlugin from 'vite-plugin-cos-uploading'

const prod = process.env.NODE_ENV === 'production'

export default defineConfig({
  plugins: [
    prod &&
      cosUploadPlugin({
        cdnHost: 'https://cdn.xxx.com',
        from: './dist/assets/**', // 上传哪些文件
        dist: '/static', // 上传到 COS 的目录前缀
        region: process.env.COS_REGION, // 如 ap-guangzhou
        // 自定义请求域名（可选，映射为 COS SDK 的 Domain），如内网域名或 CDN 源站域名
        // endpoint: 'cos-internal.ap-guangzhou.myqcloud.com',
        // secure: false, // 内网时可关闭 HTTPS
        secretId: process.env.COS_SECRET_ID,
        secretKey: process.env.COS_SECRET_KEY,
        bucket: process.env.COS_BUCKET, // 格式 name-appid，如 examplebucket-1250000000
        overwrite: true,
        quitWpOnError: true,
        // 改写资源引用的 querystring：入参与返回值均以 `?` 开头
        // 用于统一打版本号 / 缓存破坏标识，返回 `''` 可去掉查询串
        rewriteQueryString: (_path, _query) => `?v=${process.env.BUILD_VERSION ?? '1'}`,
      }),
  ].filter(Boolean),
})

对应 .env（请加入 .gitignore）：

COS_REGION=ap-guangzhou
COS_SECRET_ID=xxxxxxxx
COS_SECRET_KEY=xxxxxxxx
COS_BUCKET=examplebucket-1250000000

开发

pnpm install
pnpm build       # 构建产物（dist）
pnpm test        # 运行单元测试
pnpm test:watch  # 监听模式
pnpm lint        # 代码检查
pnpm typecheck   # 类型检查

License

MIT