vite-plugin-oss-upload

vite-plugin-oss-upload

一个可以将打包好的资源文件上传到阿里云 OSS，并把代码中资源引用替换为 CDN 地址的 Vite 插件。

特性

• 打包完成后自动上传资源文件到阿里云 OSS
• 自动重写构建产物中的资源引用为 CDN 地址
• 并发上传（可配置），支持大文件批量场景
• 支持 test 模式预演，不真正上传
• 可选删除本地原文件与空目录
• 支持从环境变量读取凭据，避免硬编码

安装

npm i vite-plugin-oss-upload -D
# 或
pnpm add vite-plugin-oss-upload -D

要求 Node.js >= 18。

配置参数

必填

参数	说明
accessKeyId	阿里云授权 accessKeyId
accessKeySecret	阿里云授权 accessKeySecret
bucket	上传到哪个 bucket
region / endpoint	二者至少配置其一。region 为区域如 oss-cn-hangzhou；endpoint 为完整访问域名（含内网域名，如 oss-cn-hangzhou-internal.aliyuncs.com），传入后优先于 region 生效

可选

参数	说明	默认值
cdnHost	上传后用于替换的资源文件 CDN 域名，留空则跳过 CDN 重写	''
from	glob 字符串，指定要上传的文件	./dist/assets/**
dist	上传到 OSS 的目录前缀	''（根目录）
timeout	OSS 单次请求超时（毫秒）	30000
overwrite	是否覆盖 OSS 同名文件	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
setOssPath	自定义 OSS 路径生成函数	以 outputDirectory 为基准的相对路径
rewriteQueryString	改写资源引用的 querystring，签名 (path, query) => string。path 为 CDN 替换前的原始资源路径；query 入参与返回值都包含 ?（如 ?v=1），无查询串时为 ''，返回 '' 表示去掉查询串	—
concurrency	并发上传数	5
secure	是否使用 HTTPS（true）/ HTTP（false）。默认随 OSS 客户端自动判断	—

内网自动探测

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

• 探测命中（内网）：自动切换为内网 endpoint，并使用 HTTP（secure: false），提升上传速度、避免公网带宽。
• 探测失败 / 超时：视为非内网，沿用用户原有配置（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 均可，插件会自动补齐 ?）；返回 '' 则去掉查询串。

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

示例：

ViteOSSPluginUpload({
  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

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

使用示例

// vite.config.js
import { defineConfig } from 'vite'
import ViteOSSPluginUpload from 'vite-plugin-oss-upload'

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

export default defineConfig({
  plugins: [
    prod &&
      ViteOSSPluginUpload({
        cdnHost: 'https://cdn.xxx.com',
        from: './dist/assets/**', // 上传哪些文件
        dist: '/static', // 上传到 OSS 的目录前缀
        // 方式一：使用 region
        region: process.env.OSS_REGION,
        // 方式二：使用自定义 endpoint（如内网域名），优先级高于 region
        // endpoint: 'oss-cn-hangzhou-internal.aliyuncs.com',
        // secure: false, // 内网时可关闭 HTTPS
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        bucket: process.env.OSS_BUCKET,
        overwrite: true,
        quitWpOnError: true,
      }),
  ].filter(Boolean),
})

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

OSS_REGION=oss-cn-hangzhou
OSS_ACCESS_KEY_ID=xxxxxxxx
OSS_ACCESS_KEY_SECRET=xxxxxxxx
OSS_BUCKET=my-bucket

开发

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

License

MIT