vite-plugin-deploy-ftp 3.3.0 → 3.4.0

package/README.md

@@ -1,17 +1,6 @@
 # vite-plugin-deploy-ftp
 
-将 dist 目录上传到 FTP 服务器，支持单个或多个 FTP 服务器配置
-
-## 介绍
-
-`vite-plugin-deploy-ftp` 是一个 Vite 插件，用于将打包后的文件上传到 FTP 服务器。插件支持：
-
-- 单个 FTP 服务器配置
-- 多个 FTP 服务器配置（可多选上传目标）
-- 自动备份远程文件
-- 连接重试机制
-- 选择性文件备份
-- 当前版本仅支持 ESM（`import`），不再提供 CommonJS（`require`）入口
+把 Vite 打包后的目录上传到 FTP，适合不想手动打开 FTP 工具、重复拖文件发布的项目。
 
 ## 安装
 
@@ -19,72 +8,137 @@
 pnpm add vite-plugin-deploy-ftp -D
 ```
 
-## 使用
+## 快速开始
 
-### 单个 FTP 配置
+推荐用环境变量控制是否上传，默认本地普通打包不上传，只有明确开启时才发布。
+
+```bash
+# .env
+FTP_HOST=ftp.example.com
+FTP_PORT=21
+FTP_USER=username
+FTP_PASSWORD=password
+FTP_PATH=/public_html
+FTP_ALIAS=https://example.com
+DEPLOY_FTP=0
+```
 
 ```ts
 // vite.config.ts
+import { defineConfig, loadEnv } from 'vite'
 import vitePluginDeployFtp from 'vite-plugin-deploy-ftp'
 
-export default {
-  plugins: [
-    vitePluginDeployFtp({
-      open: true,
-      host: 'ftp.example.com',
-      port: 21,
-      user: 'username',
-      password: 'password',
-      uploadPath: '/public_html',
-      alias: 'https://example.com',
-      singleBack: false,
-      singleBackFiles: ['index.html'],
-      maxRetries: 3,
-      retryDelay: 1000,
-    }),
-  ],
-}
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '')
+  const shouldDeploy = env.DEPLOY_FTP === '1'
+
+  return {
+    plugins: [
+      vitePluginDeployFtp({
+        open: shouldDeploy,
+        autoUpload: true,
+        failOnError: true,
+        host: env.FTP_HOST,
+        port: +(env.FTP_PORT || 21),
+        user: env.FTP_USER,
+        password: env.FTP_PASSWORD,
+        uploadPath: env.FTP_PATH?.split(',').map((path) => path.trim()) || '',
+        alias: env.FTP_ALIAS,
+        singleBack: true,
+        singleBackFiles: ['index.html'],
+      }),
+    ],
+  }
+})
+```
+
+上传时再打开开关：
+
+```bash
+# macOS / Linux
+DEPLOY_FTP=1 pnpm build
+
+# Windows PowerShell
+$env:DEPLOY_FTP='1'; pnpm build
+```
+
+`FTP_PATH` 可以写一个目录：
+
+```bash
+FTP_PATH=/public_html
+```
+
+也可以写多个目录：
+
+```bash
+FTP_PATH=/public_html,/backup_html
 ```
 
-### 多个 FTP 配置
+## 常用配置说明
+
+| 参数              | 说明                                                           |
+| ----------------- | -------------------------------------------------------------- |
+| `open`            | 是否启用上传。推荐用环境变量控制，避免普通打包时误上传。       |
+| `autoUpload`      | 是否跳过“是否上传”的确认。自动发布时建议设为 `true`。          |
+| `failOnError`     | 上传失败时是否让命令失败。发布流程里建议设为 `true`。          |
+| `uploadPath`      | 上传目录。支持字符串，也支持字符串数组，数组会上传到多个目录。 |
+| `alias`           | 访问域名。填写后，上传完成会输出可访问链接。                   |
+| `singleBack`      | 是否只备份指定文件。通常备份 `index.html` 就够，速度更快。     |
+| `singleBackFiles` | 单文件备份列表，支持子目录文件，例如 `assets/app.js`。         |
+| `ftps`            | 多个 FTP 服务器配置。需要发布到多个服务器时使用。              |
+| `defaultFtp`      | 多 FTP 时默认选中的服务器名称，可减少手动选择。                |
+| `concurrency`     | 同时上传的数量。服务器不稳定时保持默认值更稳。                 |
+
+## 重要行为说明
+
+- 插件只在 Vite 构建结束后上传。
+- `open: false` 时不会上传，也不会检查 FTP 配置。
+- `uploadPath` 传数组时，会把同一份文件依次上传到每个目录。
+- 多 FTP 和多目录可以一起使用，会按“服务器 × 目录”的组合逐个上传。
+- 上传前如果远端目录已有文件，会根据配置询问或执行备份。
+- `singleBack: true` 时，只备份 `singleBackFiles` 里的文件。
+- `autoUpload: false` 时，上传前会询问是否继续。
+- 上传失败且 `failOnError: true` 时，构建命令会失败，方便发布系统拦截。
+- 当前版本仅支持 ESM，也就是 `import`，不支持 `require`。
+
+## 风险提示
+
+- 不建议把 FTP 用户名、密码直接写进 `vite.config.ts`，推荐放到环境变量里。
+- 生产发布建议使用 `open` 环境变量开关，避免普通打包误传线上目录。
+- `uploadPath` 写成数组时，会上传到多个目录，请确认每个目录都是预期目标。
+- 完整备份会下载远端目录并重新上传压缩包，远端文件多时会比较慢。
+- 如果 FTP 服务器不稳定，不建议把 `concurrency` 调太高。
+
+## 示例
+
+### 多个 FTP 服务器
 
 ```ts
-// vite.config.ts
 import vitePluginDeployFtp from 'vite-plugin-deploy-ftp'
 
 export default {
   plugins: [
     vitePluginDeployFtp({
-      open: true,
+      open: process.env.DEPLOY_FTP === '1',
+      autoUpload: true,
       uploadPath: '/public_html',
-      singleBack: false,
-      singleBackFiles: ['index.html'],
-      maxRetries: 3,
-      retryDelay: 1000,
+      defaultFtp: 'production',
       ftps: [
         {
-          name: '生产环境',
-          host: 'ftp.production.com',
-          port: 21,
-          user: 'prod_user',
-          password: 'prod_password',
-          alias: 'https://production.com',
-        },
-        {
-          name: '测试环境',
-          host: 'ftp.test.com',
+          name: 'production',
+          host: process.env.FTP_PROD_HOST,
           port: 21,
-          user: 'test_user',
-          password: 'test_password',
-          alias: 'https://test.com',
+          user: process.env.FTP_PROD_USER,
+          password: process.env.FTP_PROD_PASSWORD,
+          alias: 'https://example.com',
         },
         {
-          name: '开发环境',
-          host: 'ftp.dev.com',
+          name: 'test',
+          host: process.env.FTP_TEST_HOST,
           port: 21,
-          user: 'dev_user',
-          password: 'dev_password',
-          alias: 'https://dev.com',
+          user: process.env.FTP_TEST_USER,
+          password: process.env.FTP_TEST_PASSWORD,
+          alias: 'https://test.example.com',
         },
       ],
     }),
@@ -92,23 +146,50 @@ export default {
 }
 ```
 
-## 配置参数
+### 多个上传目录
+
+```ts
+import vitePluginDeployFtp from 'vite-plugin-deploy-ftp'
+
+export default {
+  plugins: [
+    vitePluginDeployFtp({
+      open: process.env.DEPLOY_FTP === '1',
+      autoUpload: true,
+      host: process.env.FTP_HOST,
+      user: process.env.FTP_USER,
+      password: process.env.FTP_PASSWORD,
+      uploadPath: ['/public_html', '/backup_html'],
+      alias: 'https://example.com',
+    }),
+  ],
+}
+```
+
+## 完整配置表
 
 ### 通用参数
 
-| 参数              | 类型       | 默认值           | 说明                             |
-| ----------------- | ---------- | ---------------- | -------------------------------- |
-| `open`            | `boolean`  | `true`           | 是否启用插件                     |
-| `uploadPath`      | `string`   | -                | FTP 服务器上的上传路径           |
-| `singleBack`      | `boolean`  | `false`          | 是否使用单文件备份模式           |
-| `singleBackFiles` | `string[]` | `['index.html']` | 单文件备份模式下要备份的文件列表 |
-| `maxRetries`      | `number`   | `3`              | 连接失败时的最大重试次数         |
-| `retryDelay`      | `number`   | `1000`           | 重试延迟时间（毫秒）             |
+| 参数              | 类型                 | 默认值           | 说明                                             |
+| ----------------- | -------------------- | ---------------- | ------------------------------------------------ |
+| `open`            | `boolean`            | `true`           | 是否启用插件                                     |
+| `uploadPath`      | `string \| string[]` | -                | FTP 服务器上的上传路径，传数组时会上传到多个目录 |
+| `singleBack`      | `boolean`            | `false`          | 是否使用单文件备份模式                           |
+| `singleBackFiles` | `string[]`           | `['index.html']` | 单文件备份模式下要备份的文件列表                 |
+| `debug`           | `boolean`            | `false`          | 是否输出调试耗时                                 |
+| `maxRetries`      | `number`             | `3`              | 连接或上传失败时的最大重试次数                   |
+| `retryDelay`      | `number`             | `1000`           | 重试延迟时间，单位毫秒                           |
+| `showBackFile`    | `boolean`            | `false`          | 是否显示备份文件列表                             |
+| `autoUpload`      | `boolean`            | `false`          | 是否跳过上传确认                                 |
+| `fancy`           | `boolean`            | `true`           | 是否使用更丰富的终端输出                         |
+| `failOnError`     | `boolean`            | `true`           | 上传失败时是否中断构建命令                       |
+| `concurrency`     | `number`             | `1`              | 同时上传的任务数量                               |
 
 ### 单个 FTP 配置参数
 
 | 参数       | 类型     | 默认值 | 说明                       |
 | ---------- | -------- | ------ | -------------------------- |
+| `name`     | `string` | -      | FTP 配置名称               |
 | `host`     | `string` | -      | FTP 服务器地址             |
 | `port`     | `number` | `21`   | FTP 服务器端口             |
 | `user`     | `string` | -      | FTP 用户名                 |
@@ -117,11 +198,12 @@ export default {
 
 ### 多个 FTP 配置参数
 
-| 参数   | 类型          | 说明               |
-| ------ | ------------- | ------------------ |
-| `ftps` | `FtpConfig[]` | FTP 服务器配置数组 |
+| 参数         | 类型          | 说明                    |
+| ------------ | ------------- | ----------------------- |
+| `ftps`       | `FtpConfig[]` | FTP 服务器配置数组      |
+| `defaultFtp` | `string`      | 默认使用的 FTP 配置名称 |
 
-#### FtpConfig 对象
+### FtpConfig 对象
 
 | 参数       | 类型     | 默认值 | 说明                               |
 | ---------- | -------- | ------ | ---------------------------------- |
@@ -131,57 +213,3 @@ export default {
 | `user`     | `string` | -      | FTP 用户名                         |
 | `password` | `string` | -      | FTP 密码                           |
 | `alias`    | `string` | `''`   | 网站别名，用于生成完整 URL         |
-
-## 功能特性
-
-### 多服务器选择
-
-当使用多个 FTP 配置时，插件会显示一个多选界面，让您选择要上传到哪些服务器：
-
-```
-? 选择要上传的FTP服务器（可多选）
-❯ ◯ 生产环境
-  ◯ 测试环境
-  ◯ 开发环境
-```
-
-### 备份功能
-
-插件提供两种备份模式：
-
-1. **完整备份**: 将远程目录下的所有文件打包备份
-2. **选择性备份**: 只备份指定的文件（通过 `singleBackFiles` 配置）
-
-### 连接重试
-
-当 FTP 连接失败时，插件会自动重试，您可以通过 `maxRetries` 和 `retryDelay` 参数控制重试行为。
-
-## 环境变量示例
-
-建议将敏感信息（如用户名和密码）放在环境变量中：
-
-```bash
-# .env
-VITE_FTP_HOST=ftp.example.com
-VITE_FTP_PORT=21
-VITE_FTP_USER=username
-VITE_FTP_PASSWORD=password
-VITE_FTP_PATH=/public_html
-VITE_FTP_ALIAS=https://example.com
-```
-
-```ts
-// vite.config.ts
-export default {
-  plugins: [
-    vitePluginDeployFtp({
-      host: process.env.VITE_FTP_HOST,
-      port: +(process.env.VITE_FTP_PORT || 21),
-      user: process.env.VITE_FTP_USER,
-      password: process.env.VITE_FTP_PASSWORD,
-      uploadPath: process.env.VITE_FTP_PATH,
-      alias: process.env.VITE_FTP_ALIAS,
-    }),
-  ],
-}
-```

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Plugin } from 'vite';
 
 interface BaseOption {
-    uploadPath: string;
+    uploadPath: string | string[];
     singleBackFiles?: string[];
     singleBack?: boolean;
     debug?: boolean;

package/dist/index.js

@@ -135,7 +135,8 @@ var renderPanel = (title, rows, tone = "info", footer) => {
       const paddedLabel = padVisual(row.label, labelWidth);
       const prefix = `${paddedLabel}  `;
       const availableValueWidth = Math.max(8, innerWidth - stringWidth(prefix));
-      contentLines.push(`${chalk3.gray(prefix)}${fitVisual(row.value, availableValueWidth)}`);
+      const value = row.preserveValue ? row.value : fitVisual(row.value, availableValueWidth);
+      contentLines.push(`${chalk3.gray(prefix)}${value}`);
     }
   }
   if (footer) {
@@ -144,7 +145,10 @@ var renderPanel = (title, rows, tone = "info", footer) => {
   }
   const top = color(`\u256D${"\u2500".repeat(innerWidth + 2)}\u256E`);
   const bottom = color(`\u2570${"\u2500".repeat(innerWidth + 2)}\u256F`);
-  const body = contentLines.map((line) => `${color("\u2502")} ${fitVisual(line, innerWidth)} ${color("\u2502")}`).join("\n");
+  const body = contentLines.map((line) => {
+    const fittedLine = stringWidth(line) > innerWidth ? line : fitVisual(line, innerWidth);
+    return `${color("\u2502")} ${fittedLine} ${color("\u2502")}`;
+  }).join("\n");
   return `${top}
 ${body}
 ${bottom}`;
@@ -272,7 +276,8 @@ var renderBackupPanel = (summary) => {
     { label: "\u7ED3\u679C:", value: chalk5.green(`${summary.items.length} \u4E2A\u5907\u4EFD\u6587\u4EF6`) },
     ...previewItems.map((item, index) => ({
       label: `\u6587\u4EF6 ${index + 1}:`,
-      value: chalk5.cyan(truncateTerminalText(item, 22))
+      value: chalk5.cyan(item),
+      preserveValue: true
     }))
   ];
   if (summary.items.length > previewItems.length) {
@@ -311,7 +316,12 @@ function vitePluginDeployFtp(option) {
   const isMultiFtp = "ftps" in safeOption;
   const ftpConfigs = isMultiFtp ? safeOption.ftps || [] : [{ ...safeOption, name: safeOption.name || safeOption.alias || safeOption.host }];
   const defaultFtp = isMultiFtp ? safeOption.defaultFtp : void 0;
-  const normalizedUploadPath = normalizeFtpUploadPath(uploadPath);
+  const uploadPaths = Array.isArray(uploadPath) ? uploadPath : [uploadPath];
+  const normalizedUploadPaths = Array.from(
+    new Set(
+      uploadPaths.map((targetPath) => typeof targetPath === "string" ? normalizeFtpUploadPath(targetPath) : "/")
+    )
+  );
   let outDir = normalizePath2(path2.resolve("dist"));
   let upload = false;
   let buildFailed = false;
@@ -323,7 +333,14 @@ function vitePluginDeployFtp(option) {
   };
   const validateOptions = () => {
     const errors = [];
-    if (!uploadPath) errors.push("uploadPath is required");
+    if (uploadPaths.length === 0) {
+      errors.push("uploadPath is required");
+    }
+    uploadPaths.forEach((targetPath, index) => {
+      if (typeof targetPath !== "string" || targetPath.trim() === "") {
+        errors.push(`uploadPath${uploadPaths.length > 1 ? `[${index}]` : ""} is required`);
+      }
+    });
     if (!Number.isInteger(maxRetries) || maxRetries < 1) errors.push("maxRetries must be >= 1");
     if (!Number.isFinite(retryDelay) || retryDelay < 0) errors.push("retryDelay must be >= 0");
     if (!Number.isInteger(concurrency) || concurrency < 1) errors.push("concurrency must be >= 1");
@@ -737,7 +754,7 @@ function vitePluginDeployFtp(option) {
     );
     return { results, debugEntries };
   };
-  const deploySingleTarget = async (ftpConfig) => {
+  const deploySingleTarget = async (ftpConfig, normalizedUploadPath) => {
     const { host, port = 21, user, password, alias = "", name } = ftpConfig;
     const normalizedAlias = alias ? normalizeUrlLikeBase(alias) : "";
     if (!host || !user || !password) {
@@ -757,10 +774,11 @@ function vitePluginDeployFtp(option) {
     });
     const totalFiles = allFiles.length;
     const displayName = name || host;
+    const resultName = normalizedUploadPaths.length > 1 ? `${displayName} ${normalizedUploadPath}` : displayName;
     const startTime = Date.now();
     if (allFiles.length === 0) {
       console.log(`${getLogSymbol("warning")} \u6CA1\u6709\u627E\u5230\u9700\u8981\u4E0A\u4F20\u7684\u6587\u4EF6`);
-      return { name: displayName, totalFiles: 0, failedCount: 0 };
+      return { name: resultName, totalFiles: 0, failedCount: 0 };
     }
     clearScreen();
     console.log(
@@ -903,7 +921,7 @@ function vitePluginDeployFtp(option) {
         }
       ];
       if (accessUrl) {
-        resultRows.push({ label: "\u8BBF\u95EE:", value: chalk5.cyan(truncateTerminalText(accessUrl, 20)) });
+        resultRows.push({ label: "\u8BBF\u95EE:", value: chalk5.cyan(accessUrl), preserveValue: true });
       }
       if (failedCount > 0) {
         const failedItems = results.filter((result) => !result.success).slice(0, 2);
@@ -936,7 +954,7 @@ function vitePluginDeployFtp(option) {
         });
         console.log(renderDebugPanel(debugEntries));
       }
-      return { name: displayName, totalFiles: results.length, failedCount };
+      return { name: resultName, totalFiles: results.length, failedCount };
     } catch (error) {
       if (preflightSpinner) preflightSpinner.stop();
       console.log(`
@@ -950,7 +968,7 @@ ${getLogSymbol("danger")} \u4E0A\u4F20\u8FC7\u7A0B\u4E2D\u53D1\u751F\u9519\u8BEF
         console.log(renderDebugPanel(debugEntries));
       }
       return {
-        name: displayName,
+        name: resultName,
         totalFiles,
         failedCount: totalFiles > 0 ? totalFiles : 1,
         error: error instanceof Error ? error : new Error(String(error))
@@ -1021,8 +1039,10 @@ ${getLogSymbol("danger")} \u4E0A\u4F20\u8FC7\u7A0B\u4E2D\u53D1\u751F\u9519\u8BEF
     }
     const deployResults = [];
     for (const ftpConfig of selectedConfigs) {
-      const targetResult = await deploySingleTarget(ftpConfig);
-      deployResults.push(targetResult);
+      for (const normalizedUploadPath of normalizedUploadPaths) {
+        const targetResult = await deploySingleTarget(ftpConfig, normalizedUploadPath);
+        deployResults.push(targetResult);
+      }
     }
     return deployResults;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-deploy-ftp",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",