nuxt-alioss-upload

Nuxt 模块：构建完成后将静态资源上传到阿里云 OSS，作为 CDN 分发。

在 close 钩子中，将 .output/public 下的构建产物上传到指定环境的 OSS bucket，实现「构建 → 压缩 → 上传」的一键部署流程中的上传环节。

安装

本包为独立 npm 包，直接通过包管理器安装即可：

pnpm add nuxt-alioss-upload
# 或
npm install nuxt-alioss-upload

快速开始

在 nuxt.config.ts 中注册模块并配置（按环境区分）：

// nuxt.config.ts
interface AliOssUploadEnvConfig {
  static: string      // OSS bucket 内对象 key 前缀，即 CDN 访问路径
  region: string      // OSS region，如 oss-cn-beijing
  accessKeyId: string
  accessKeySecret: string
  bucket: string
  host: string        // CDN 访问地址
}

const aliossUpload: Record<string, AliOssUploadEnvConfig> = {
  beta: {
    static: 'your-site-test',
    region: 'oss-cn-beijing',
    accessKeyId: '...',
    accessKeySecret: '...',
    bucket: 'your-bucket-test',
    host: 'https://your-cdn.example.com/your-site-test',
  },
  prod: {
    static: 'your-site',
    region: 'oss-cn-beijing',
    accessKeyId: '...',
    accessKeySecret: '...',
    bucket: 'your-bucket',
    host: 'https://your-cdn.example.com/your-site',
  },
}

export default defineNuxtConfig({
  modules: ['nuxt-alioss-upload'],
  aliossUpload,
})

模块顺序：modules: ['tinify-img', 'nuxt-alioss-upload'] —— 先压缩后上传。

配置项

aliossUpload 类型：Record<构建环境, 配置>，key 为 dev | beta | prod 之一。

| 字段 | 类型 | 说明 | |------|------|------| | static | string | OSS bucket 内的对象 key 前缀（即 CDN 访问路径） | | region | string | OSS region，如 oss-cn-beijing | | accessKeyId | string | 阿里云 AccessKey ID | | accessKeySecret | string | 阿里云 AccessKey Secret | | bucket | string | OSS bucket 名称 | | host | string | CDN 访问地址 |

环境选择

模块使用 BUILD_ENV 而非 NODE_ENV 决定使用哪份配置：

function resolveBuildEnv(): string {
  return process.env.BUILD_ENV || process.env.NODE_ENV || 'dev'
}

原因：nuxt generate 会强制将 NODE_ENV 设为 production，无法据此区分 beta / prod，因此用 .env.* 中的 BUILD_ENV 区分环境（如 .env.beta 设 BUILD_ENV=beta）。

工作原理

1. 触发时机：close 钩子（构建结束时）。
2. 跳过条件：
   • dev 模式、prepare 阶段（类型生成）均跳过——避免误传残留旧产物。
   • 找不到当前环境的配置，或缺少 accessKeyId/accessKeySecret 时打印警告并跳过。
3. 上传内容：
   • _nuxt/ 目录下的静态资源（忽略 **/*.html 与 ssr-manifest.json）。
   • 所有 _payload.json（Nuxt prerender 生成的预取数据，忽略 _nuxt/ 内的）。
4. 对象 key：${prefix}/${相对 .output/public 的路径}，其中 prefix 为 static 去除末尾斜杠。
5. 并发控制：以 10 为一批（CONCURRENCY = 10）使用 Promise.allSettled 并发上传，统计成功/失败数量与耗时。

日志输出

[nuxt-alioss-upload] Uploading build output to OSS (env=prod, bucket=your-bucket, static=your-site)
[nuxt-alioss-upload] ✅ your-site/_nuxt/index.a1b2c3.js
[nuxt-alioss-upload] ✅ your-site/_payload.json
[nuxt-alioss-upload] Done: 120 uploaded, 0 failed, cost 3.42s

注意事项

• 不要在 nuxt.config.ts 中硬编码真实 AccessKey 到公开仓库；建议通过环境变量或 CI 机密注入。
• 上传仅覆盖 _nuxt/ 与 _payload.json，不包含 HTML 页面（由 CDN / 托管侧处理）。
• 若需上传其他产物，可在 close 钩子中自行扩展。

相关

• nuxt-tinify-img — 构建时压缩图片（与 nuxt-alioss-upload 配合：先压缩后上传）。
• 阿里云 OSS 文档：https://help.aliyun.com/zh/oss/