vite-plugin-deploy-archive

Deploy Vite build output to an SSH server with timestamped remote .tar.gz backups.

• English
• 中文

English

What It Does

vite-plugin-deploy-archive provides an explicit deployment command for Vite projects.

• vite build only builds. It never uploads files by itself.
• deploy-archive deploy builds or reuses your output directory, creates a local .tar.gz archive, backs up the current remote files, uploads the new archive over SFTP, extracts it, and switches the remote directory with the configured strategy.
• deploy-archive check checks whether the remote server is ready for deploy.
• deploy-archive init creates local config templates for beginners.

The package includes both a Vite plugin and a CLI. The CLI performs deployment. The Vite plugin records build metadata during deploy mode so the CLI can use the actual Vite build.outDir.

Install

npm install -D vite-plugin-deploy-archive

Supported Vite peer range:

vite ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0

Vite 8 requires Node.js 20.19+ or 22.12+.

Quick Start

Initialize config files:

npx deploy-archive init --yes

Add the Vite plugin:

import { defineConfig } from 'vite'
import deployArchive from 'vite-plugin-deploy-archive'

export default defineConfig({
  plugins: [deployArchive()],
})

Fill the generated .deploy-archive.config.* and .env.deploy-archive.example values. Rename or copy the env example into your own .env or target-specific env file.

Check the remote server:

npx deploy-archive check

Preview the deploy plan:

npx deploy-archive deploy --dry-run

Deploy explicitly:

npx deploy-archive deploy --yes

CLI Commands

deploy-archive init

Creates:

• .deploy-archive.config.*
• .deploy-archive.config.example.*
• .env.deploy-archive.example

By default, the real config file is treated as local sensitive config. The init command appends these deploy-archive rules to .gitignore unless --public-config is used:

# deploy-archive local config
.deploy-archive.config.*
!.deploy-archive.config.example.*

It does not modify .env* ignore rules. It creates only an env example file.

Options:

| Option | Description | | --- | --- | | --yes | Accept defaults and add "deploy": "deploy-archive deploy" to package.json when possible. | | --force | Overwrite generated config/example files. | | --public-config | Do not add deploy config ignore rules to .gitignore. Use this when your real config is safe to commit. | | --overwrite-script | Overwrite an existing scripts.deploy entry when used with --yes. | | --format <format> | Force generated config format: ts, js, cjs, or json. | | --auth <auth> | Choose generated auth template: password or privateKey. |

When --format is not provided, init detects the project style:

1. TypeScript project: .deploy-archive.config.ts
2. ESM JavaScript project: .deploy-archive.config.js
3. CommonJS or unknown project: .deploy-archive.config.cjs

TypeScript detection checks tsconfig.json, vite.config.ts, vite.config.mts, and the typescript dependency.

deploy-archive deploy [...args]

Runs the selected build unless --skip-build is used, creates the artifact, and deploys it to the selected target.

Options:

| Option | Description | | --- | --- | | --target <target> | Deploy a named target from targets. | | --config <path> | Load a specific config file instead of auto discovery. | | --dry-run | Print a redacted deploy plan. Does not build, connect, upload, or modify remote files. | | --skip-build | Deploy an existing output directory. Uses output.dir or dist; does not read the Vite manifest. | | --yes | Skip the confirmation prompt. Useful in CI. | | --build-script <script> | Override the configured/package build script for this run. | | --build-command <command> | Override the build with trusted shell syntax for this run. | | [...] | Extra positional args are passed to the selected build script or command. |

Examples:

npx deploy-archive deploy --dry-run
npx deploy-archive deploy --target staging --yes
npx deploy-archive deploy --build-script build:staging -- --mode staging
npx deploy-archive deploy --build-command "vite build --mode staging"
npx deploy-archive deploy --skip-build --target production --yes

--build-script and --build-command are mutually exclusive.

deploy-archive check

Validates the selected config and connects to the remote server over SSH. It checks required remote commands and whether temp.remoteDir can be created and written.

Options:

| Option | Description | | --- | --- | | --target <target> | Check a named target from targets. | | --config <path> | Load a specific config file instead of auto discovery. |

Config Files

Auto discovery order:

1. .deploy-archive.config.ts
2. .deploy-archive.config.mts
3. .deploy-archive.config.js
4. .deploy-archive.config.mjs
5. .deploy-archive.config.cjs
6. .deploy-archive.config.json

TypeScript, ESM, CommonJS, and JSON config files are supported. JavaScript and TypeScript configs can read process.env. JSON configs support ${ENV_NAME} interpolation.

Environment Loading

The CLI loads env files before reading config:

1. .env
2. .env.local
3. .env.<target>
4. .env.<target>.local
5. Existing process environment values win over file values.

For single-target config or when no --target is provided, only .env and .env.local are loaded.

Vite Plugin Options

import deployArchive from 'vite-plugin-deploy-archive'

deployArchive({
  manifestPath: 'node_modules/.cache/deploy-archive/manifest.json',
})

| Option | Type | Default | Description | | --- | --- | --- | --- | | manifestPath | string | node_modules/.cache/deploy-archive/manifest.json under the Vite project root | Where the plugin writes deploy-mode build metadata. Most projects should leave this unset. |

The plugin writes the manifest only when the CLI runs the build in deploy mode. Plain vite build does not write deploy metadata and does not deploy.

Configuration Shapes

Single target:

import { defineConfig } from 'vite-plugin-deploy-archive'

export default defineConfig({
  deploy: {
    host: process.env.DEPLOY_HOST || '',
    username: process.env.DEPLOY_USER || '',
    remoteDir: process.env.DEPLOY_REMOTE_DIR || '',
    auth: {
      type: 'password',
      password: process.env.DEPLOY_PASSWORD || '',
    },
    confirm: true,
  },
  backup: {
    remoteDir: process.env.DEPLOY_BACKUP_DIR || '',
  },
})

Multiple targets:

import { defineConfig } from 'vite-plugin-deploy-archive'

export default defineConfig({
  defaultTarget: 'staging',
  build: {
    script: 'build',
  },
  output: {
    dir: 'dist',
  },
  upload: {
    exclude: ['**/*.map'],
  },
  targets: {
    staging: {
      deploy: {
        host: process.env.STAGING_DEPLOY_HOST || '',
        username: process.env.STAGING_DEPLOY_USER || '',
        remoteDir: '/var/www/my-app-staging',
        auth: {
          type: 'password',
          password: process.env.STAGING_DEPLOY_PASSWORD || '',
        },
        confirm: true,
      },
      backup: {
        remoteDir: '/var/backups/my-app-staging',
      },
    },
    production: {
      deploy: {
        host: process.env.PROD_DEPLOY_HOST || '',
        username: process.env.PROD_DEPLOY_USER || '',
        remoteDir: '/var/www/my-app',
        auth: {
          type: 'privateKey',
          privateKey: process.env.PROD_DEPLOY_PRIVATE_KEY_PATH || '~/.ssh/id_rsa',
          passphrase: process.env.PROD_DEPLOY_PRIVATE_KEY_PASSPHRASE,
        },
        confirm: true,
      },
      backup: {
        remoteDir: '/var/backups/my-app',
      },
    },
  },
})

In multi-target config, root-level build, output, backup, upload, and temp are defaults. A target can override them.

Complete Configuration Reference

Root Fields

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | defaultTarget | string | No | First key in targets | Multi-target only. Target used when --target is not provided. | | build | BuildConfig | No | See build | Root build defaults. In single-target config it applies directly; in multi-target config targets can override it. | | output | OutputConfig | No | {} | Output directory fallback settings. | | deploy | DeployConfig | Yes for single target | None | Remote deploy settings. Not allowed at root in multi-target config. | | backup | BackupConfig | No | See backup | Backup settings. | | upload | UploadConfig | No | See upload | Artifact upload settings. | | temp | TempConfig | No | See temp | Local and remote temporary directories. | | targets | Record<string, TargetConfig> | Yes for multi-target | None | Named deployment targets. |

deploy

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | host | string | Yes | None | SSH host name or IP address. | | port | number | No | 22 | SSH port. Must be an integer from 1 to 65535. | | username | string | Yes | None | SSH username. | | remoteDir | string | Yes | None | Absolute Unix path that will contain the deployed app. Dangerous roots such as /, /home, /var, /usr, /opt, and /tmp are rejected. | | auth | AuthConfig | Yes | None | SSH authentication config. | | strategy | 'atomic' | No | 'atomic' | Deployment strategy. Currently only atomic is supported. | | confirm | boolean | No | false in code, true in generated templates | When true, interactive deploy asks for confirmation unless --yes is used. In non-interactive mode, use --yes. |

deploy.auth

Password auth:

auth: {
  type: 'password',
  password: process.env.DEPLOY_PASSWORD || '',
}

| Field | Type | Required | Description | | --- | --- | --- | --- | | type | 'password' | Yes | Selects password authentication. | | password | string | Yes | SSH password. Redacted from dry-run output. |

Private key auth:

auth: {
  type: 'privateKey',
  privateKey: process.env.DEPLOY_PRIVATE_KEY_PATH || '~/.ssh/id_rsa',
  passphrase: process.env.DEPLOY_PRIVATE_KEY_PASSPHRASE,
}

| Field | Type | Required | Description | | --- | --- | --- | --- | | type | 'privateKey' | Yes | Selects private key authentication. | | privateKey | string | Yes | Private key content or a local private key path. ~ is expanded to the user home directory. | | passphrase | string | No | Private key passphrase. Redacted from dry-run output. |

SSH agent auth:

auth: {
  type: 'agent',
  agent: process.env.SSH_AUTH_SOCK,
}

| Field | Type | Required | Description | | --- | --- | --- | --- | | type | 'agent' | Yes | Selects SSH agent authentication. | | agent | string | No | SSH agent socket. Defaults to SSH_AUTH_SOCK. |

build

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | script | string | No | Auto-detected | Package script name, for example build or build:prod. Runs through the detected package manager with structured args. | | command | string | No | Auto-detected | Trusted shell command, for example vite build --mode production. Use only when you need shell syntax. |

build.script and build.command are mutually exclusive.

Build selection priority:

1. CLI --build-script or --build-command
2. Target build.script or build.command
3. Root build.script or build.command
4. package.json scripts.build
5. Fallback command vite build

Passthrough args are appended to the selected build. For scripts, they are added after --:

npx deploy-archive deploy --build-script build:prod -- --mode production

output

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | dir | string | No | dist fallback | Output directory fallback. Can be absolute or relative to the project root. |

Normal deploy uses the Vite plugin manifest outDir first. If the manifest is missing or ignored, it falls back to output.dir, then dist. --skip-build uses output.dir or dist directly.

The selected output directory must exist and contain at least one file.

backup

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | enabled | boolean | No | true | Whether to create a remote backup before switching releases. | | remoteDir | string | Required when enabled | None | Absolute Unix directory where backup archives are stored. Dangerous roots are rejected. | | filename | string | No | {name}-{yyyyMMdd-HHmmss}.tar.gz | Backup filename template. Must end with .tar.gz. | | onFailure | 'abort' \| 'continue' | No | 'abort' | Whether a backup failure stops deployment. continue is risky and should be used only when acceptable. |

Supported filename placeholders:

| Placeholder | Meaning | | --- | --- | | {name} | Target name. Single-target config uses app. | | {yyyyMMdd-HHmmss} | UTC timestamp, for example 20260609-093000. |

If the remote app directory is missing or empty, backup is skipped and deploy continues. This handles first-time deployment.

upload

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | include | string[] | No | ['**/*'] | Fast-glob patterns included in the local artifact. | | exclude | string[] | No | OS junk files are excluded | Fast-glob ignore patterns. Added to default excludes. | | method | 'archive' | No | 'archive' | Upload method. Currently only archive upload is supported. |

Default excludes:

**/.DS_Store
**/Thumbs.db
**/desktop.ini
**/__MACOSX/**

The artifact contains files inside the output directory, not the absolute output directory itself.

temp

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | localDir | string | No | node_modules/.cache/deploy-archive under the project root | Local directory used to create the .tar.gz artifact. | | remoteDir | string | No | /tmp/deploy-archive | Remote directory used for uploaded artifacts and extracted releases. Must be writable by the SSH user. |

Remote Server Requirements

The target server must be Unix-like and reachable over SSH/SFTP. Windows remote hosts are not supported.

Required remote commands:

sh mkdir tar mv rm test ls find

Run deploy-archive check before the first deploy and whenever server permissions change.

Safety Notes

• Deployment is explicit. vite build never deploys.
• Keep real config and env files out of git when they contain secrets.
• Prefer private key or SSH agent auth for automation. Password auth is supported when your server allows it.
• Use deploy.confirm: true for interactive manual deploys.
• Use --dry-run before changing a new target.
• Use target-specific env files such as .env.production.local for secrets.
• backup.onFailure: 'continue' can leave you without a fresh backup for that deploy. Use it only when that risk is acceptable.

中文

功能说明

vite-plugin-deploy-archive 为 Vite 项目提供显式部署命令。

• vite build 只会打包，不会自动上传。
• deploy-archive deploy 会执行或复用打包产物，创建本地 .tar.gz 压缩包， 备份当前远程文件，通过 SFTP 上传新压缩包，远程解压，并按配置策略切换远程目录。
• deploy-archive check 用于检查远程服务器是否满足部署要求。
• deploy-archive init 用于生成适合新手起步的配置模板。

包里包含 Vite 插件和 CLI。真正执行部署的是 CLI。Vite 插件只在 deploy 模式下记录 构建元数据，让 CLI 能拿到 Vite 实际解析后的 build.outDir。

安装

npm install -D vite-plugin-deploy-archive

支持的 Vite peer 范围：

vite ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0

Vite 8 需要 Node.js 20.19+ 或 22.12+。

快速开始

初始化配置文件：

npx deploy-archive init --yes

添加 Vite 插件：

import { defineConfig } from 'vite'
import deployArchive from 'vite-plugin-deploy-archive'

export default defineConfig({
  plugins: [deployArchive()],
})

填写生成的 .deploy-archive.config.* 和 .env.deploy-archive.example。 可以把 env example 改名或复制成自己的 .env 或目标环境专用 env 文件。

检查远程服务器：

npx deploy-archive check

预览部署计划：

npx deploy-archive deploy --dry-run

显式部署：

npx deploy-archive deploy --yes

CLI 命令

deploy-archive init

创建：

• .deploy-archive.config.*
• .deploy-archive.config.example.*
• .env.deploy-archive.example

默认情况下，真实配置文件会被当作本地敏感配置处理。除非使用 --public-config，否则 init 会向 .gitignore 追加以下 deploy-archive 规则：

# deploy-archive local config
.deploy-archive.config.*
!.deploy-archive.config.example.*

它不会修改 .env* 的 ignore 规则，只会创建 env 示例文件。

参数：

| 参数 | 说明 | | --- | --- | | --yes | 接受默认选项，并在可行时向 package.json 添加 "deploy": "deploy-archive deploy"。 | | --force | 覆盖已生成的配置和示例文件。 | | --public-config | 不向 .gitignore 添加部署配置忽略规则。适合真实配置可以提交的项目。 | | --overwrite-script | 配合 --yes 使用，覆盖已有的 scripts.deploy。 | | --format <format> | 指定生成配置格式：ts、js、cjs 或 json。 | | --auth <auth> | 指定生成认证模板：password 或 privateKey。 |

未指定 --format 时，init 会自动判断项目类型：

1. TypeScript 项目：.deploy-archive.config.ts
2. ESM JavaScript 项目：.deploy-archive.config.js
3. CommonJS 或未知项目：.deploy-archive.config.cjs

TypeScript 判断会检查 tsconfig.json、vite.config.ts、vite.config.mts 以及 typescript 依赖。

deploy-archive deploy [...args]

除非使用 --skip-build，否则会执行选中的构建命令，然后创建压缩包并部署到目标服务器。

参数：

| 参数 | 说明 | | --- | --- | | --target <target> | 部署 targets 中的某个命名目标。 | | --config <path> | 指定配置文件路径，不走自动发现。 | | --dry-run | 打印脱敏后的部署计划。不会构建、连接、上传或修改远程文件。 | | --skip-build | 部署已有输出目录。使用 output.dir 或 dist，不会读取 Vite manifest。 | | --yes | 跳过确认提示，适合 CI。 | | --build-script <script> | 本次运行临时覆盖配置或 package 中的构建脚本。 | | --build-command <command> | 本次运行临时使用可信 shell 命令构建。 | | [...] | 额外位置参数会继续传给选中的构建脚本或命令。 |

示例：

npx deploy-archive deploy --dry-run
npx deploy-archive deploy --target staging --yes
npx deploy-archive deploy --build-script build:staging -- --mode staging
npx deploy-archive deploy --build-command "vite build --mode staging"
npx deploy-archive deploy --skip-build --target production --yes

--build-script 和 --build-command 互斥。

deploy-archive check

校验选中配置，并通过 SSH 连接远程服务器。它会检查远程必需命令是否存在， 以及 temp.remoteDir 是否可以创建和写入。

参数：

| 参数 | 说明 | | --- | --- | | --target <target> | 检查 targets 中的某个命名目标。 | | --config <path> | 指定配置文件路径，不走自动发现。 |

配置文件

自动发现顺序：

1. .deploy-archive.config.ts
2. .deploy-archive.config.mts
3. .deploy-archive.config.js
4. .deploy-archive.config.mjs
5. .deploy-archive.config.cjs
6. .deploy-archive.config.json

支持 TypeScript、ESM、CommonJS 和 JSON 配置文件。JavaScript 和 TypeScript 配置可以读取 process.env。JSON 配置支持 ${ENV_NAME} 环境变量插值。

环境变量加载顺序

CLI 会在读取配置前加载 env 文件：

1. .env
2. .env.local
3. .env.<target>
4. .env.<target>.local
5. 已存在的进程环境变量优先级最高，会覆盖文件值。

单目标配置或未传 --target 时，只会加载 .env 和 .env.local。

Vite 插件选项

import deployArchive from 'vite-plugin-deploy-archive'

deployArchive({
  manifestPath: 'node_modules/.cache/deploy-archive/manifest.json',
})

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | manifestPath | string | Vite 项目根目录下的 node_modules/.cache/deploy-archive/manifest.json | deploy 模式下写入构建元数据的位置。大多数项目无需配置。 |

插件只会在 CLI 以 deploy 模式执行构建时写 manifest。普通 vite build 不会写部署元数据，也不会部署。

配置形态

单目标：

import { defineConfig } from 'vite-plugin-deploy-archive'

export default defineConfig({
  deploy: {
    host: process.env.DEPLOY_HOST || '',
    username: process.env.DEPLOY_USER || '',
    remoteDir: process.env.DEPLOY_REMOTE_DIR || '',
    auth: {
      type: 'password',
      password: process.env.DEPLOY_PASSWORD || '',
    },
    confirm: true,
  },
  backup: {
    remoteDir: process.env.DEPLOY_BACKUP_DIR || '',
  },
})

多目标：

import { defineConfig } from 'vite-plugin-deploy-archive'

export default defineConfig({
  defaultTarget: 'staging',
  build: {
    script: 'build',
  },
  output: {
    dir: 'dist',
  },
  upload: {
    exclude: ['**/*.map'],
  },
  targets: {
    staging: {
      deploy: {
        host: process.env.STAGING_DEPLOY_HOST || '',
        username: process.env.STAGING_DEPLOY_USER || '',
        remoteDir: '/var/www/my-app-staging',
        auth: {
          type: 'password',
          password: process.env.STAGING_DEPLOY_PASSWORD || '',
        },
        confirm: true,
      },
      backup: {
        remoteDir: '/var/backups/my-app-staging',
      },
    },
    production: {
      deploy: {
        host: process.env.PROD_DEPLOY_HOST || '',
        username: process.env.PROD_DEPLOY_USER || '',
        remoteDir: '/var/www/my-app',
        auth: {
          type: 'privateKey',
          privateKey: process.env.PROD_DEPLOY_PRIVATE_KEY_PATH || '~/.ssh/id_rsa',
          passphrase: process.env.PROD_DEPLOY_PRIVATE_KEY_PASSPHRASE,
        },
        confirm: true,
      },
      backup: {
        remoteDir: '/var/backups/my-app',
      },
    },
  },
})

多目标配置中，根级 build、output、backup、upload、temp 是默认值， 每个 target 可以覆盖它们。

完整配置参数

根字段

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | defaultTarget | string | 否 | targets 的第一个 key | 仅多目标配置使用。未传 --target 时使用该目标。 | | build | BuildConfig | 否 | 见 build | 根级构建默认值。单目标配置中直接生效；多目标配置中可被 target 覆盖。 | | output | OutputConfig | 否 | {} | 输出目录兜底配置。 | | deploy | DeployConfig | 单目标必填 | 无 | 远程部署配置。多目标配置中不放在根级。 | | backup | BackupConfig | 否 | 见 backup | 备份配置。 | | upload | UploadConfig | 否 | 见 upload | 压缩包和上传配置。 | | temp | TempConfig | 否 | 见 temp | 本地和远程临时目录配置。 | | targets | Record<string, TargetConfig> | 多目标必填 | 无 | 命名部署目标。 |

deploy

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | host | string | 是 | 无 | SSH 主机名或 IP。 | | port | number | 否 | 22 | SSH 端口。必须是 1 到 65535 的整数。 | | username | string | 是 | 无 | SSH 用户名。 | | remoteDir | string | 是 | 无 | 部署应用所在的远程绝对 Unix 路径。会拒绝 /、/home、/var、/usr、/opt、/tmp 等危险根目录。 | | auth | AuthConfig | 是 | 无 | SSH 鉴权配置。 | | strategy | 'atomic' | 否 | 'atomic' | 部署策略。目前仅支持 atomic。 | | confirm | boolean | 否 | 代码默认 false，生成模板默认 true | 为 true 时，交互式部署会要求确认；使用 --yes 可跳过。非交互环境请使用 --yes。 |

deploy.auth

密码鉴权：

auth: {
  type: 'password',
  password: process.env.DEPLOY_PASSWORD || '',
}

| 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | type | 'password' | 是 | 使用密码鉴权。 | | password | string | 是 | SSH 密码。dry-run 输出会脱敏。 |

私钥鉴权：

auth: {
  type: 'privateKey',
  privateKey: process.env.DEPLOY_PRIVATE_KEY_PATH || '~/.ssh/id_rsa',
  passphrase: process.env.DEPLOY_PRIVATE_KEY_PASSPHRASE,
}

| 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | type | 'privateKey' | 是 | 使用私钥鉴权。 | | privateKey | string | 是 | 私钥内容或本地私钥路径。~ 会展开为用户 home 目录。 | | passphrase | string | 否 | 私钥 passphrase。dry-run 输出会脱敏。 |

SSH agent 鉴权：

auth: {
  type: 'agent',
  agent: process.env.SSH_AUTH_SOCK,
}

| 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | type | 'agent' | 是 | 使用 SSH agent 鉴权。 | | agent | string | 否 | SSH agent socket。默认使用 SSH_AUTH_SOCK。 |

build

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | script | string | 否 | 自动选择 | package script 名称，例如 build 或 build:prod。会通过检测到的包管理器运行，并使用结构化参数。 | | command | string | 否 | 自动选择 | 可信 shell 命令，例如 vite build --mode production。只有需要 shell 语法时才建议使用。 |

build.script 和 build.command 互斥。

构建选择优先级：

1. CLI --build-script 或 --build-command
2. target 里的 build.script 或 build.command
3. 根级 build.script 或 build.command
4. package.json 的 scripts.build
5. 兜底命令 vite build

透传参数会附加给选中的构建。对于 script，会追加在 -- 后：

npx deploy-archive deploy --build-script build:prod -- --mode production

output

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | dir | string | 否 | 兜底为 dist | 输出目录兜底值。可以是绝对路径，也可以是相对项目根目录的路径。 |

正常部署会优先使用 Vite 插件 manifest 中记录的 outDir。如果 manifest 缺失或被忽略， 再回退到 output.dir，最后回退到 dist。--skip-build 会直接使用 output.dir 或 dist。

选中的输出目录必须存在，并且目录内至少包含一个文件。

backup

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | enabled | boolean | 否 | true | 是否在切换发布版本前创建远程备份。 | | remoteDir | string | 启用备份时必填 | 无 | 远程备份压缩包保存目录，必须是绝对 Unix 路径，会拒绝危险根目录。 | | filename | string | 否 | {name}-{yyyyMMdd-HHmmss}.tar.gz | 备份文件名模板，必须以 .tar.gz 结尾。 | | onFailure | 'abort' \| 'continue' | 否 | 'abort' | 备份失败时是否终止部署。continue 风险更高，只应在可接受时使用。 |

支持的文件名占位符：

| 占位符 | 含义 | | --- | --- | | {name} | 目标名称。单目标配置使用 app。 | | {yyyyMMdd-HHmmss} | UTC 时间戳，例如 20260609-093000。 |

如果远程应用目录不存在或为空，会跳过备份并继续部署。这用于支持首次部署。

upload

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | include | string[] | 否 | ['**/*'] | 本地压缩包包含的 fast-glob 规则。 | | exclude | string[] | 否 | 默认排除常见系统垃圾文件 | fast-glob 忽略规则，会追加到默认排除规则后。 | | method | 'archive' | 否 | 'archive' | 上传方式。目前仅支持压缩包上传。 |

默认排除：

**/.DS_Store
**/Thumbs.db
**/desktop.ini
**/__MACOSX/**

压缩包包含的是输出目录内部的文件，不包含输出目录自身的绝对路径。

temp

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | localDir | string | 否 | 项目根目录下的 node_modules/.cache/deploy-archive | 本地创建 .tar.gz 压缩包的临时目录。 | | remoteDir | string | 否 | /tmp/deploy-archive | 远程上传压缩包和解压 release 的临时目录。SSH 用户必须可写。 |

远程服务器要求

目标服务器必须是类 Unix 系统，并且可以通过 SSH/SFTP 访问。不支持 Windows 远程主机。

远程必需命令：

sh mkdir tar mv rm test ls find

首次部署前，以及服务器权限调整后，建议运行 deploy-archive check。

注意事项

• 部署是显式的，vite build 永远不会部署。
• 如果真实配置和 env 文件包含密钥或密码，不要提交到 git。
• 自动化部署建议优先使用私钥或 SSH agent。服务器允许时也支持账号密码。
• 手动部署建议设置 deploy.confirm: true。
• 对新目标部署前先运行 --dry-run。
• 密钥建议放在 .env.production.local 这类目标专用 env 文件中。
• backup.onFailure: 'continue' 可能导致本次部署没有新备份。只有能接受该风险时才使用。