前端项目部署只要30秒

简单部署

简单部署 是一款 VS Code 扩展，用来把本地打包好的前端或静态站点一键上传到 Linux 服务器，自动备份旧代码、解压新包、替换上线，让发布流程更简单。

它能做什么

把 Vue、React 等前端项目构建产物（如 dist/）一键上传到 Linux 服务器并替换上线。
把后台管理系统部署到服务器子目录（如 /var/www/admin），配合前置命令实现"构建 + 上线"一步完成。
把 VitePress、Docusaurus 等生成的静态站点或文档站点一键发布。
同一套代码配置多个项目，分别发布到测试、生产等不同环境。
部署前自动执行本地命令（如 bun run build），命令失败则停止部署。
部署前自动备份旧代码，新包先解压到临时目录再整体替换，避免半完成状态。
通过保留规则保护服务器上的上传目录、配置文件等不被删除。
实时展示部署进度、阶段状态和滚动日志，保留最近 100 条部署记录。

使用前提

VS Code 版本 >= 1.101.0。
目标服务器必须是 Linux，并且已安装 unzip 命令。
服务器使用账号 + 密码登录，暂不支持 SSH 密钥。

第一次使用

点击 VS Code 左侧 Activity Bar 的 简单部署 图标，打开面板。
切换到 服务器 标签，添加你的服务器信息。
切换到 项目 标签，添加部署项目。
点击项目卡片，确认规则后点击 确认部署。
等待部署完成，复制日志或关闭面板。

扩展依赖 随易商店 进行授权管理，首次使用前需要完成授权或试用。

界面说明

面板入口

左侧 Activity Bar 点击 简单部署 图标打开面板。
面板顶部可切换 项目 / 服务器 两个标签。
顶部右侧显示授权状态、购买/试用按钮、设置中心。

项目卡片

展示项目名称、目标服务器、部署路径，点击卡片开始部署。

服务器卡片

展示服务器名称和账号信息，支持编辑、删除。

添加服务器

打开 简单部署 面板，切换到 服务器 标签。
点击 添加服务器。
填写表单： - 服务器名称 ：给服务器起个名字，方便识别，可以不填。 - Host / IP ：服务器地址。 - 端口：SSH 端口，默认 22。 - 用户名 ：SSH 登录用户名。 - 密码：创建时必须填写；编辑时留空表示不改密码。
点击 保存。

密码会安全保存在 VS Code 内部，不会明文显示。

服务器准备工作

建议在服务器上创建一个专用部署账号，并把目标目录权限交给它：

bash 复制代码

sudo useradd -m deploy
sudo passwd deploy
sudo chown -R deploy:deploy /var/www/app
sudo chmod -R u+rwx /var/www/app

添加项目

切换到 项目 标签，点击 添加项目。
填写表单： - 项目名称 ：必填，比如"官网前端"。 - 目标服务器 ：必填，从已保存的服务器中选择。 - 远程路径 ：必填，服务器上的部署目录，比如 /var/www/app。 - 前置命令 ：可选，部署前先在本地执行的命令。 - 上传规则 ：必填，要上传哪些文件或目录。 - 删除规则 ：可选，部署前先删除服务器上的哪些文件。 - 保留规则：可选，哪些文件即使命中删除规则也不要删。
点击 保存。

各项配置说明

远程路径

服务器上要部署到的目录。

必须以 / 开头。
不能包含 ..。
至少要有 2 级目录，比如 /var/www/app。
不能是 /、/var 这类系统目录。

路径	是否允许
`/var/www/app`	✅
`/var/www`	✅
`/var`	❌ 太短
`/`	❌ 系统根目录
`/var/www/../etc`	❌ 包含 `..`

上传规则

用来指定哪些本地文件要上传到服务器，使用 glob 写法：

符号	含义
`*`	匹配同一层目录里的任意字符，不含 `/`。
`**`	匹配任意层级的目录。
`?`	匹配一个字符。
`!` 开头	排除，比如 `!node_modules/**`。

常见写法：

dist/**：上传 dist 目录里的所有内容。
dist/index.html：只上传单个文件。
assets/*.png：上传 assets 下的所有 png 图片。
!node_modules/**：排除 node_modules。

注意：dist 会把整个 dist 目录上传；dist/ 或 dist/** 只上传 dist 里面的内容。

上传根目录

每条上传规则都可以指定一个上传根目录：

不填时系统会自动计算。
手动填写时，必须是这条规则的前缀。
比如规则是 dist/**，自动上传根目录就是 dist。

为什么需要上传根目录？

上传根目录决定了 zip 包内部的顶层结构。服务器解压后，文件会按照这个结构摆放。

示例：

规则 dist/**，上传根目录 dist - 本地文件：dist/index.html、dist/assets/main.js - 服务器解压后：index.html、assets/main.js - 也就是去掉了 dist 这一层目录，适合前端项目直接把构建产物放到网站根目录。
规则 dist/** - 如果不填上传根目录，系统也会自动算成 dist，效果和上面一样。
规则 public/**，上传根目录 public - 本地文件：public/logo.png - 服务器解压后：logo.png

删除规则

作用：

部署前，先把服务器上匹配的旧文件或目录删除掉，避免旧文件残留影响新版本。

适用场景：

前端项目每次构建后文件名会变化（比如带 hash 的 assets/main-abc123.js），旧文件不会自动消失，需要定期清理。
想彻底清空某个目录，比如旧版 assets/ 下的所有文件。
删除服务器上不再需要的临时文件，比如 **/*.zip。

写法示例：

规则	会删除什么
`assets/*`	删除 `assets` 目录下直接一层的所有文件，不删子目录。
`assets/**`	删除 `assets` 目录下的所有内容，包括子目录。
`index.html`	删除单个文件。
`*/.zip`	删除所有 zip 文件，不管在哪一层。

注意事项：

删除规则匹配不到的内容会原样保留。
如果配置了保留规则，保留规则会覆盖删除规则，被保留的文件不会被删。
删除操作在服务器端执行，删除前会先列出匹配列表并在日志中展示数量。

保留规则

作用：

告诉扩展哪些文件或目录即使命中了删除规则，也不要删除。

适用场景：

服务器上有用户上传的文件目录，比如 uploads/，每次部署时都不想被清空。
有配置文件或日志文件需要保留，比如 config.json、logs/。
旧版资源中有些文件新版本没有，但需要继续保留。

写法示例：

规则	保留什么
`uploads/`	保留 `uploads` 整个目录及其内容。
`logo.png`	保留单个文件。
`assets/legacy.css`	保留 `assets` 目录下的 `legacy.css`。
`*/.config.json`	保留所有以 `.config.json` 结尾的文件。

注意事项：

保留规则优先级高于删除规则。
保留规则本身也是 glob 写法，支持 *、?、**。
保留的文件会在部署时被移动到新包临时目录，清空旧目录后再随新包一起发布。

前置命令

作用：

在打包上传之前，先在本地执行一些命令，通常用来重新构建项目，确保上传的是最新产物。

适用场景：

部署前先 bun run build 或 npm run build。
部署前先压缩图片、生成 sitemap、执行测试等。
多步骤构建，比如先 build 再压缩。

字段说明：

字段	说明
命令	要在终端执行的命令，比如 `bun run build`。
执行目录	命令在哪个目录下执行。留空表示项目根目录；填写时表示项目根目录下的子目录。

写法示例：

命令	执行目录	说明
`bun run build`	留空	在项目根目录执行构建，生成 `dist/`。
`npm run build`	留空	同上，使用 npm。
`bun run compress`	`dist`	构建完成后，进入 `dist` 目录执行压缩。
`python scripts/copy_assets.py`	留空	执行项目根目录下的 Python 脚本。

注意事项：

前置命令按添加顺序依次执行。
只要有一条命令执行失败（退出码不是 0），整个部署就会终止。
命令和执行目录都不能包含特殊符号，也不能以 / 开头或包含 ..。
执行目录是相对项目根目录的，不是绝对路径。

规则通用限制

上传规则、删除规则、保留规则、前置命令的执行目录都遵循以下限制：

不能以 / 开头。
不能包含 ..。
不能包含 shell 危险字符：; & | $ ( ) { } \ < > ! # ~`。
不能是单独的 * 或 **。

这些限制是为了防止误操作和命令注入，保障部署安全。

部署流程

点击 确认部署 后，扩展会按顺序做以下事情：

准备部署：记录项目、工作区、规则等基本信息。
执行前置命令：按顺序执行本地命令，失败则终止。
压缩本地文件：把匹配的文件打包成 zip，临时放在系统 tmp 目录。
连接服务器：通过 SSH 登录服务器，并检查必须是 Linux 系统。
备份旧代码 ：把服务器上的旧代码打包备份到 ~/.static-deploy/.../backups/，最多保留 20 份。
上传文件：通过 SFTP 上传 zip，实时显示进度和速度。
校验并解压新包：在服务器上校验 zip 完整性，解压到临时目录。
清空旧文件：清空目标目录里的旧内容，但保留目录本身。
替换为新目录：把临时目录替换为正式的目标目录。
清理临时文件：删除服务器上的临时目录和本地的临时 zip。
部署完成：显示成功或失败结果。

部署面板介绍

部署开始后，会进入部署面板：

左侧部署日志：按阶段分组展示日志，命令输出可以展开/收起。点击某个阶段会高亮右侧对应步骤，点击右侧步骤也会高亮左侧日志。
右侧部署阶段：展示 11 个阶段的状态。灰色表示未开始，绿色表示完成，蓝色表示进行中，红色表示出错。
底部进度区：显示当前步骤名称、百分比进度条、部署结果。

如果部署失败，可以从备份自动恢复，并清理临时文件。

安全提示

密码使用 VS Code 内部加密存储，不会明文保存。
远程路径必须通过安全校验，禁止系统根目录等危险路径。
项目名称、规则、命令等输入都会过滤危险字符，降低注入风险。
新包先解压到临时目录，再替换正式目录，避免半完成状态。
同一时间只能有一个部署任务在执行。

常见问题

部署失败提示"仅支持 Linux 服务器"

请确认目标服务器是 Linux 系统。

部署失败提示"未找到该服务器的密码"

编辑对应服务器，重新输入密码并保存。

前置命令执行失败

请先在本地终端手动执行该命令，确认可以正常运行，再检查执行目录是否正确。

上传后文件层级不对

检查上传规则。dist/** 会上传 dist 里面的内容；如果想保留 dist 这一层目录，请使用 dist。

保留规则没生效

保留规则优先级高于删除规则，但要确保规则写法能匹配到实际路径。

联系我们

开发者微信：chensuiyime
官网地址：https://yicode.tech