简单部署
简单部署 是一款 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 内部，不会明文显示。
服务器准备工作
建议在服务器上创建一个专用部署账号，并把目标目录权限交给它：
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
