vite-plugin-deploy-oss 3.3.0 → 3.4.0

package/.prettierignore

@@ -0,0 +1,5 @@
+dist
+node_modules
+playground/__dist__
+coverage
+*.log

package/.prettierrc.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "arrowParens": "always",
+  "bracketSameLine": false,
+  "jsxSingleQuote": true,
+  "printWidth": 120,
+  "quoteProps": "as-needed",
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "endOfLine": "lf"
+}

package/README.md

@@ -1,10 +1,6 @@
 # vite-plugin-deploy-oss
 
-将 dist 目录上传到 OSS
-
-## 介绍
-
-`vite-plugin-deploy-oss` 是一个 Vite 插件，它可以将你的 dist 目录上传到 OSS 上。
+把 Vite 打包后的文件上传到阿里云 OSS。
 
 ## 安装
 
@@ -12,53 +8,92 @@
 pnpm add vite-plugin-deploy-oss -D
 ```
 
-## 使用
+## 快速开始
+
+推荐用环境变量控制上传，避免本地随手打包时误上传。
 
 ```ts
 // vite.config.ts
+import { defineConfig } from 'vite'
 import vitePluginDeployOss from 'vite-plugin-deploy-oss'
 
-// ...existing code...
-export default {
-  // ...existing code...
+export default defineConfig({
   plugins: [
-    // 在最后一个插件中使用
     vitePluginDeployOss({
-      // 建议按环境变量开关上传，避免本地/CI误上传
       open: process.env.DEPLOY_OSS === '1',
-      // 终端实时动效进度面板（默认 true）
-      fancy: true,
 
-      accessKeyId: '***',
-      accessKeySecret: '***',
-      bucket: '***',
-      region: '***',
-      uploadDir: `H5/zz/test`,
-      skip: ['**/index.html'],
+      accessKeyId: process.env.OSS_ACCESS_KEY_ID || '',
+      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET || '',
+      bucket: process.env.OSS_BUCKET || '',
+      region: process.env.OSS_REGION || '',
 
-      // 默认 true：有上传失败时抛错并让构建失败
-      failOnError: true,
+      uploadDir: 'H5/demo/prod',
+      configBase: 'https://example.com/H5/demo/prod/',
 
-      // 生成并上传 OSS 汇总文件
       manifest: true,
-
-      // 修改打包后的资源路径
-      configBase: `https://oss.eventnet.cn/H5/zz/test/`,
+      failOnError: true,
     }),
   ],
-}
+})
+```
+
+发布时执行：
+
+```bash
+DEPLOY_OSS=1 pnpm build
+```
+
+## 常用配置
+
+| 配置              | 默认值            | 说明                               |
+| ----------------- | ----------------- | ---------------------------------- |
+| `open`            | `true`            | 是否开启上传。建议用环境变量控制。 |
+| `accessKeyId`     | -                 | OSS 访问密钥。                     |
+| `accessKeySecret` | -                 | OSS 访问密钥。                     |
+| `bucket`          | -                 | OSS bucket 名称。                  |
+| `region`          | -                 | OSS 区域，例如 `oss-cn-beijing`。  |
+| `uploadDir`       | -                 | 文件上传到 OSS 的目标目录。        |
+| `configBase`      | -                 | 同步修改 Vite 的资源访问路径。     |
+| `skip`            | `'**/index.html'` | 不上传的文件规则。                 |
+| `overwrite`       | `true`            | 是否允许覆盖远端同名文件。         |
+| `autoDelete`      | `false`           | 上传成功后是否删除本地构建文件。   |
+| `manifest`        | `false`           | 是否生成并上传文件清单。           |
+| `failOnError`     | `true`            | 上传失败时是否中断构建。           |
+| `debug`           | `false`           | 是否输出耗时信息。                 |
+| `fancy`           | `true`            | 是否显示更友好的终端进度。         |
+
+## 重要行为
+
+- `open: true` 时，如果缺少 `accessKeyId`、`accessKeySecret`、`bucket`、`region` 或 `uploadDir`，会直接中断构建。
+- `manifest` 开启后，会自动上传全部文件，并自动保留本地构建文件。
+- `manifest` 开启后，`skip` 会按空数组处理，`autoDelete` 会按 `false` 处理。
+- `oss-manifest.json` 只记录本次成功上传的文件，不包含清单文件自身。
+- `configBase` 会影响 Vite 打包后的资源路径，也会影响清单里的访问地址。
+- `alias` 只影响清单里生成的访问地址，不会改变实际上传路径。
+
+## Manifest
+
+开启：
+
+```ts
+vitePluginDeployOss({
+  // ...其他配置
+  manifest: true,
+})
 ```
 
-## 说明
+自定义文件名：
 
-- 当前版本仅支持 ESM（`import`），不再提供 CommonJS（`require`）入口。
-- `open` 默认 `true`，建议通过环境变量控制开关（例如 `DEPLOY_OSS=1` 时再上传）。
-- `fancy` 默认 `true`，TTY 终端下会显示实时动效进度（速度、预计剩余、并发、当前文件）。
-- `failOnError` 默认 `true`，上传有失败会抛错，适合 CI 场景保证发布质量。
-- `manifest` 默认关闭。开启后会在构建目录生成并上传 `oss-manifest.json`。
-- `manifest: true` 时默认文件名为 `oss-manifest.json`，也支持 `manifest: { fileName: 'meta/oss-manifest.json' }` 自定义路径。
-- `oss-manifest.json` 仅包含本次成功上传的文件，不包含汇总文件自身。
-- `oss-manifest.json` 内容示例：
+```ts
+vitePluginDeployOss({
+  // ...其他配置
+  manifest: {
+    fileName: 'meta/oss-manifest.json',
+  },
+})
+```
+
+清单内容示例：
 
 ```json
 {
@@ -66,10 +101,34 @@ export default {
   "files": [
     {
       "file": "assets/index-abc123.js",
-      "key": "H5/zz/test/assets/index-abc123.js",
-      "url": "https://oss.eventnet.cn/H5/zz/test/assets/index-abc123.js",
+      "key": "H5/demo/prod/assets/index-abc123.js",
+      "url": "https://example.com/H5/demo/prod/assets/index-abc123.js",
       "md5": "d41d8cd98f00b204e9800998ecf8427e"
     }
   ]
 }
 ```
+
+## 调试
+
+开启 `debug` 后，构建结束会额外输出关键步骤耗时，方便判断慢在哪里。
+
+```ts
+vitePluginDeployOss({
+  // ...其他配置
+  debug: process.env.DEPLOY_OSS_DEBUG === '1',
+})
+```
+
+也可以使用项目内的 playground 命令：
+
+```bash
+pnpm run build:test:debug
+```
+
+## 注意事项
+
+- 建议不要在配置里直接写真实密钥，优先使用环境变量。
+- 建议生产发布时保持 `failOnError: true`，避免部分文件没上传却继续完成流程。
+- 如果开启 `autoDelete`，请确认不需要保留本地构建文件。
+- 当前版本仅支持 ESM，也就是 `import` 用法，不提供 `require` 入口。

package/dist/index.d.ts

@@ -18,6 +18,7 @@ interface vitePluginDeployOssOption extends Omit<oss.Options, 'accessKeyId' | 'a
     autoDelete?: boolean;
     skip?: string | string[];
     open?: boolean;
+    debug?: boolean;
     fancy?: boolean;
     noCache?: boolean;
     failOnError?: boolean;

package/dist/index.js

@@ -179,6 +179,18 @@ ${body}
 ${bottom}`;
 };
 var renderInlineStats = (items) => items.filter(Boolean).join(chalk2.gray(" \xB7 "));
+var getPanelDot = (tone = "success") => {
+  switch (tone) {
+    case "info":
+      return chalk2.green("\u25CF");
+    case "success":
+      return chalk2.green("\u25CF");
+    case "warning":
+      return chalk2.yellow("\u25CF");
+    case "danger":
+      return chalk2.red("\u25CF");
+  }
+};
 var getLogSymbol = (tone) => {
   switch (tone) {
     case "success":
@@ -191,6 +203,20 @@ var getLogSymbol = (tone) => {
 };
 
 // src/index.ts
+var formatTimingDuration = (durationMs) => {
+  if (durationMs < 1e3) return `${durationMs}ms`;
+  const seconds = durationMs / 1e3;
+  return `${seconds.toFixed(seconds >= 10 ? 1 : 2)}s`;
+};
+var renderDebugPanel = (entries) => {
+  const rows = entries.map((entry) => ({
+    label: `${entry.label}:`,
+    value: chalk3.cyan(
+      entry.detail ? `${formatTimingDuration(entry.durationMs)} \xB7 ${truncateTerminalText(entry.detail, 24)}` : formatTimingDuration(entry.durationMs)
+    )
+  }));
+  return renderPanel(`${getPanelDot("success")} \u8C03\u8BD5\u8017\u65F6`, rows, "info");
+};
 var createManifestPayload = async (results, configBase, alias) => {
   const successfulResults = results.filter((result) => result.success);
   const files = await Promise.all(
@@ -223,6 +249,7 @@ function vitePluginDeployOss(option) {
     autoDelete = false,
     alias,
     open = true,
+    debug = false,
     fancy = true,
     noCache = false,
     failOnError = true,
@@ -235,6 +262,9 @@ function vitePluginDeployOss(option) {
   const normalizedUploadDir = normalizePathSegments(uploadDir);
   const normalizedConfigBase = configBase ? ensureTrailingSlash(normalizeUrlLikeBase(configBase)) : void 0;
   const normalizedAlias = alias ? normalizeUrlLikeBase(alias) : void 0;
+  const manifestFileName = resolveManifestFileName(manifest);
+  const effectiveAutoDelete = manifestFileName ? false : autoDelete;
+  const effectiveSkip = manifestFileName ? [] : Array.isArray(skip) ? skip : [skip];
   let buildFailed = false;
   let upload = false;
   let outDir = normalizePath(resolve2("dist"));
@@ -277,7 +307,7 @@ function vitePluginDeployOss(option) {
           headers
         });
         if (result.res.status === 200) {
-          if (autoDelete) {
+          if (effectiveAutoDelete) {
             try {
               await unlink(task.filePath);
             } catch (error) {
@@ -334,12 +364,14 @@ function vitePluginDeployOss(option) {
   };
   const uploadFilesInBatches = async (client, files, windowSize = concurrency) => {
     const results = [];
+    const debugEntries = [];
     const totalFiles = files.length;
     const tasks = [];
     let completed = 0;
     let failed = 0;
     let uploadedBytes = 0;
     let retries = 0;
+    const taskPrepareStartedAt = Date.now();
     const taskCandidates = await Promise.all(
       files.map(async (relativeFilePath) => {
         const filePath = normalizePath(resolve2(outDir, relativeFilePath));
@@ -352,6 +384,11 @@ function vitePluginDeployOss(option) {
         }
       })
     );
+    debugEntries.push({
+      label: "\u751F\u6210\u4E0A\u4F20\u4EFB\u52A1",
+      durationMs: Date.now() - taskPrepareStartedAt,
+      detail: `${files.length} \u4E2A\u6587\u4EF6`
+    });
     for (const candidate of taskCandidates) {
       if (candidate.task) {
         tasks.push(candidate.task);
@@ -453,7 +490,12 @@ function vitePluginDeployOss(option) {
     } else {
       console.log(`${getLogSymbol("success")} \u6240\u6709\u6587\u4EF6\u4E0A\u4F20\u5B8C\u6210 (${totalFiles}/${totalFiles})`);
     }
-    return results;
+    debugEntries.push({
+      label: "\u4E0A\u4F20\u6587\u4EF6",
+      durationMs: Date.now() - startAt,
+      detail: `${tasks.length} \u4E2A\u6210\u529F\u5019\u9009 \xB7 \u5E76\u53D1 ${safeWindowSize}`
+    });
+    return { results, debugEntries };
   };
   return {
     name: "vite-plugin-deploy-oss",
@@ -466,9 +508,8 @@ function vitePluginDeployOss(option) {
       if (!open || buildFailed) return;
       const validationErrors = validateOptions();
       if (validationErrors.length > 0) {
-        console.log(`${chalk3.red("\u2717 \u914D\u7F6E\u9519\u8BEF:")}
+        throw new Error(`vite-plugin-deploy-oss \u914D\u7F6E\u9519\u8BEF:
 ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
-        return;
       }
       upload = true;
       config.base = normalizedConfigBase || config.base;
@@ -484,13 +525,19 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
       async handler() {
         if (!open || !upload || buildFailed || !resolvedConfig) return;
         const startTime = Date.now();
+        const debugEntries = [];
         const client = new oss({ region, accessKeyId, accessKeySecret, secure, bucket, ...props });
-        const manifestFileName = resolveManifestFileName(manifest);
+        const collectFilesStartedAt = Date.now();
         const files = globSync("**/*", {
           cwd: outDir,
           nodir: true,
-          ignore: Array.isArray(skip) ? skip : [skip]
+          ignore: effectiveSkip
         }).map((file) => normalizePath(file)).filter((file) => file !== manifestFileName);
+        debugEntries.push({
+          label: "\u626B\u63CF\u672C\u5730\u6587\u4EF6",
+          durationMs: Date.now() - collectFilesStartedAt,
+          detail: `${files.length} \u4E2A\u6587\u4EF6`
+        });
         if (files.length === 0) {
           console.log(`${getLogSymbol("warning")} \u6CA1\u6709\u627E\u5230\u9700\u8981\u4E0A\u4F20\u7684\u6587\u4EF6`);
           return;
@@ -498,7 +545,7 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
         clearViewport();
         console.log(
           renderPanel(
-            "\u51C6\u5907\u90E8\u7F72",
+            `${getPanelDot("success")} \u51C6\u5907\u90E8\u7F72`,
             [
               { label: "\u4F4D\u7F6E:", value: chalk3.green(`${bucket} \xB7 ${region}`) },
               {
@@ -519,7 +566,11 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
           )
         );
         try {
-          const results = await uploadFilesInBatches(client, files, concurrency);
+          const uploadExecution = await uploadFilesInBatches(client, files, concurrency);
+          const { results, debugEntries: uploadDebugEntries } = uploadExecution;
+          if (debug) {
+            debugEntries.push(...uploadDebugEntries);
+          }
           const successCount = results.filter((r) => r.success).length;
           const failedCount = results.length - successCount;
           const durationSeconds = (Date.now() - startTime) / 1e3;
@@ -531,13 +582,22 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
             const manifestRelativeFilePath = manifestFileName;
             const manifestFilePath = normalizePath(resolve2(outDir, manifestRelativeFilePath));
             const manifestObjectKey = normalizeObjectKey(normalizedUploadDir, manifestRelativeFilePath);
+            const manifestStartedAt = Date.now();
             await mkdir(dirname(manifestFilePath), { recursive: true });
             await writeFile(
               manifestFilePath,
               JSON.stringify(await createManifestPayload(results, normalizedConfigBase, normalizedAlias), null, 2),
               "utf8"
             );
+            if (debug) {
+              debugEntries.push({
+                label: "\u751F\u6210\u6E05\u5355\u6587\u4EF6",
+                durationMs: Date.now() - manifestStartedAt,
+                detail: manifestRelativeFilePath
+              });
+            }
             const manifestStats = await stat(manifestFilePath);
+            const manifestUploadStartedAt = Date.now();
             const manifestResult = await uploadSingleTask(client, {
               filePath: manifestFilePath,
               relativeFilePath: manifestRelativeFilePath,
@@ -548,6 +608,13 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
             if (!manifestResult.success) {
               throw manifestResult.error || new Error(`Failed to upload manifest: ${manifestRelativeFilePath}`);
             }
+            if (debug) {
+              debugEntries.push({
+                label: "\u4E0A\u4F20\u6E05\u5355\u6587\u4EF6",
+                durationMs: Date.now() - manifestUploadStartedAt,
+                detail: manifestRelativeFilePath
+              });
+            }
             const manifestUrl = resolveUploadedFileUrl(
               manifestRelativeFilePath,
               manifestObjectKey,
@@ -557,7 +624,14 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
             manifestSummary = truncateTerminalText(manifestUrl || manifestObjectKey, 20);
           }
           try {
+            const cleanupStartedAt = Date.now();
             await removeEmptyDirectories(outDir);
+            if (debug) {
+              debugEntries.push({
+                label: "\u6E05\u7406\u7A7A\u76EE\u5F55",
+                durationMs: Date.now() - cleanupStartedAt
+              });
+            }
           } catch (error) {
             console.warn(`${getLogSymbol("warning")} \u6E05\u7406\u7A7A\u76EE\u5F55\u5931\u8D25: ${error}`);
           }
@@ -596,11 +670,18 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
           }
           console.log(
             renderPanel(
-              failedCount === 0 ? `${getLogSymbol("success")} \u90E8\u7F72\u5B8C\u6210` : `${getLogSymbol("warning")} \u90E8\u7F72\u5B8C\u6210`,
+              failedCount === 0 ? `${getPanelDot("success")} \u90E8\u7F72\u5B8C\u6210` : `${getPanelDot("warning")} \u90E8\u7F72\u5B8C\u6210`,
               resultRows,
               failedCount === 0 ? "success" : "warning"
             )
           );
+          if (debug) {
+            debugEntries.push({
+              label: "\u603B\u8017\u65F6",
+              durationMs: Date.now() - startTime
+            });
+            console.log(renderDebugPanel(debugEntries));
+          }
           if (failedCount > 0 && failOnError) {
             throw new Error(`Failed to upload ${failedCount} of ${results.length} files`);
           }
@@ -608,6 +689,13 @@ ${validationErrors.map((err) => `  - ${err}`).join("\n")}`);
           console.log(`
 ${getLogSymbol("danger")} \u4E0A\u4F20\u8FC7\u7A0B\u4E2D\u53D1\u751F\u9519\u8BEF: ${error}
 `);
+          if (debug && debugEntries.length > 0) {
+            debugEntries.push({
+              label: "\u5931\u8D25\u524D\u8017\u65F6",
+              durationMs: Date.now() - startTime
+            });
+            console.log(renderDebugPanel(debugEntries));
+          }
           if (failOnError) {
             throw error instanceof Error ? error : new Error(String(error));
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-deploy-oss",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
@@ -32,7 +32,8 @@
   "description": "将dist目录下的文件上传到阿里云oss",
   "devDependencies": {
     "@types/ali-oss": "^6.23.3",
-    "@types/node": "^22.19.13",
+    "@types/node": "^22.19.19",
+    "prettier": "3.8.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
@@ -44,16 +45,19 @@
     "ali-oss": "^6.23.0",
     "chalk": "^5.6.2",
     "cli-progress": "^3.12.0",
-    "cli-truncate": "^5.2.0",
+    "cli-truncate": "^6.0.0",
     "glob": "^13.0.6",
     "log-symbols": "^7.0.1",
-    "string-width": "^8.2.0"
+    "string-width": "^8.2.1"
   },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc -p tsconfig.json",
     "pack": "pnpm run build && pnpm pack",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "build:test": "cd playground && vite build",
-    "build:test:deploy": "cd playground && vite build --mode deploy"
+    "build:test:deploy": "cd playground && vite build --mode deploy",
+    "build:test:debug": "cd playground && vite build --mode deploy-debug"
   }
 }

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: false