quick-fe-cli
v2.13.1
Published
前端开发工具集 - 部署项目
Readme
Quick (quick-fe-cli) - 前端开发工具集
轻量级、可扩展的 CLI 工具集，通过 SSH 将前端构建产物部署到远程服务器，支持 Windows 环境。
特性
- 🚀 SSH 部署 - tar.gz 压缩后上传，高效传输
- 🔨 自动构建 - 部署前自动检查依赖并执行构建
- 📦 包管理器支持 - 自动检测 npm / pnpm / yarn，缺失自动全局安装
- 🌐 多环境 - 开发、测试、生产独立配置
- ➕ 动态添加 - 初始化后可随时添加新环境（
quick deploy add） - 🔀 同服务器多路径 - 一台服务器部署多个应用
- 💾 自动备份 - 部署前自动备份，按 maxCount 自动清理
- 🧾 构建日志追溯 - 自动生成
.quick-release构建日志，记录本次构建对应的 Git 变更 - 📦 日志入包 - deploy 时自动把构建日志复制到
dist/.quick-release/**，随部署包上传并进入后续备份 - 🔁 日志提交推送 - deploy 构建日志会提交并推送到被打包项目的 Git 远程仓库
- ⏪ 一键回滚 - 快速回滚到任意历史备份版本
- 🎣 生命周期钩子 - 在任意阶段注入自定义逻辑
- 📖 Skill 系统 - 为 AI 编码助手（Trae/Claude/Codex）安装项目使用指南
- 🎨 彩色日志 - 基于 chalk 的终端输出和格式化表格
- 🪟 Windows 兼容 - 中文编码自动修复（GBK → UTF-8），绝对路径支持
- 🔌 可扩展 - 命令组设计，后续可扩展更多工具命令
快速开始
安装
npm install -g quick-fe-cli初始化
# 交互式初始化（推荐，分步确认）
quick deploy init
# 一键生成（默认模板，快速上手）
quick deploy init -y使用
# 部署
quick deploy dev # 部署到开发环境
quick deploy dev,prod # 部署多个环境
quick deploy dev -i # 交互模式（逐步确认）
# 回滚
quick deploy rollback dev # 交互式选择版本
quick deploy rollback dev --latest # 回滚到最近备份
quick deploy rollback dev --version my_project_back_20260430170949
# 添加新环境
quick deploy add prod # 交互式添加生产环境
quick deploy add staging # 交互式添加预发环境
# 查询
quick deploy list # 列出所有环境
quick deploy backups dev # 列出备份（时间格式化显示）
# 版本发布
quick release build # 构建、生成版本日志、提交并打 tag，不发布 npm
quick release npm # 基于当前版本发布到 npm
quick release log # 仅生成部署日志并提交推送（不做版本变更）
# Skill 管理
quick skill list # 查看内置 Skill
quick skill install # 交互式选择 Skill 并安装到 AI 平台
quick skill install deploy # 直接安装 deploy skill
# 其他
quick deploy init # 初始化配置
quick --help # 查看帮助
quick deploy --help # 查看部署命令组帮助
quick skill --help # 查看 Skill 命令组帮助版本发布
首次准备
# 安装依赖（包含 release-it）
npm install
# 登录 npm
npm login发布新版本
发布流程已拆分为两步：先构建并生成版本日志，再基于当前版本发布到 npm。
# 第一步：打包构建、生成 CHANGELOG、更新版本、Git commit/tag
quick release build
# 指定版本号类型
quick release build --major # 2.0.0 → 3.0.0（不兼容更新）
quick release build --minor # 2.0.0 → 2.1.0（新功能）
quick release build --patch # 2.0.0 → 2.0.1（Bug 修复）
# 指定自定义版本号
quick release build --version 2.11.0
# 跳过构建命令 / 跳过推送
# --skip-build 仍会生成 .quick-release 构建日志，只是不执行 npm run build
quick release build --skip-build
quick release build --no-push
# 第二步：根据当前 package.json 版本发布到 npm
quick release npm
quick release npm --dry-run # npm publish 预演
# npm script 方式（本仓库开发时可直接使用）
npm run release:build
npm run release:npm
npm run release # 等同于 release:build + release:npm发布流程
quick release build # 构建 + 版本日志 + Git commit/tag
↓
npm run build # 编译 TypeScript
↓
生成 .quick-release/build-log.json
生成 .quick-release/logs/build-YYYYMMDD-HHmmss.md
↓
分析 Git 提交记录 # 基于上次 tag 后的所有提交
↓
建议版本类型 # feat → minor, fix → patch
↓
确认/选择版本号 # 也可手动输入自定义版本号
↓
生成 CHANGELOG # 按类型分组 + 版本摘要 + commit body 补充
↓
📋 CHANGELOG 预览 # ✅ 确认 / ✏️ 编辑 / ❌ 取消（可反复编辑）
↓
Git add + commit # chore: release v2.1.0
↓
Git tag + 可选 push # 打标签，可选择是否推送到远程
↓
quick release npm # 发布当前版本到 npm构建日志与部署追溯
每次执行 quick release build 或 quick deploy env 的构建阶段，都会在当前被构建项目中生成：
.quick-release/build-log.json
.quick-release/logs/build-YYYYMMDD-HHmmss.md其中：
build-log.json：记录构建来源、环境、版本、构建命令、当前 commit、上次构建信息，以及本次 Git 日志 Markdown 路径。logs/build-YYYYMMDD-HHmmss.md：记录上次构建到本次构建之间的 Git 提交，格式与CHANGELOG.md风格一致。
build-log.json 示例
{
"source": "deploy",
"env": "dev",
"projectName": "my_project",
"version": "2.10.1",
"command": "npm run build-only",
"cwd": "C:/A_code/my_project",
"distPath": "C:/A_code/my_project/dist",
"commit": "abc1234",
"builtAt": "2026-05-07T08:30:00.000Z",
"previousBuild": {
"commit": "def5678",
"builtAt": "2026-05-06T10:00:00.000Z"
},
"gitLog": {
"range": "def5678..HEAD",
"commitCount": 3,
"mdPath": "C:/A_code/my_project/.quick-release/logs/build-20260507-163000.md",
"relativeMdPath": ".quick-release/logs/build-20260507-163000.md"
}
}Markdown 日志示例
# Build dev my_project
> 构建时间：2026-05-07 16:30:00
> Git 范围：def5678..HEAD
> 1 个新功能、1 个修复
### ✨ Features
- **deploy**: 支持发布构建日志
### 🐛 Bug Fixes
- 修复 quick --version 读取错误quick deploy env 的日志处理
quick deploy env 会额外执行以下动作：
在
envConfig.projectDir对应的被打包项目中生成.quick-release/**。只提交以下文件到该项目 Git 仓库：
.quick-release/build-log.json .quick-release/logs/build-YYYYMMDD-HHmmss.md提交成功后自动推送到远程仓库。
不自动 bump 版本、不生成正式
CHANGELOG.md、不打 tag。将构建日志复制到：
dist/.quick-release/build-log.json dist/.quick-release/logs/build-YYYYMMDD-HHmmss.md压缩
distDir时，日志会一起进入部署包。服务器部署目录会包含
.quick-release/**，后续该版本被备份时，备份包中也会保留对应构建日志。
如果构建日志提交或推送失败，CLI 会输出 warning 并继续部署，避免 Git 网络或权限问题阻断线上发布。
quick release log - 独立日志生成
如果你只想在业务项目中生成部署日志并提交推送，而不需要完整的版本发布或 SSH 部署，可以使用 quick release log 命令：
# 在业务项目根目录执行
cd my_project
# 使用 package.json 中的 build script，生成日志并提交推送
quick release log
# 交互模式
quick release log -i
# 跳过构建，仅生成日志
quick release log --skip-build
# 手动指定构建命令
quick release log --cmd "npm run build:prod"
# 指定产物目录
quick release log --dist dist
# 不推送到远程
quick release log --no-push
# 跳过所有确认
quick release log -y与其他命令的区别：
quick release build：完整版本发布（构建 → 版本 bump → CHANGELOG → commit → tag → 可选 push）quick release log：仅部署日志（构建 → 生成日志 → commit → push），不做版本变更quick deploy env：完整部署（构建 → 生成日志 → 压缩 → SSH → 上传 → 部署）
quick release log 适用于只想记录构建日志并推送到 Git，而不需要版本发布或 SSH 部署的场景。
CHANGELOG 自动生成
每次发布自动生成更新内容，特性包括：
- 自动获取提交：从上次 tag 到当前 HEAD 的所有提交（无 tag 时获取全部）
- 版本摘要：
> 4 个新功能、2 个修复、1 个重构 - 分类展示：Features / Bug Fixes / Performance / Refactoring / Documentation / Chores
- 详细说明：自动提取 commit body 作为补充说明
- 过滤噪声：自动排除
chore: release提交 - 交互式编辑：预览后选择 ✏️ 编辑，打开系统编辑器手动修改内容
CHANGELOG 示例：
## [2.5.0] (2026-04-30)
> 4 个新功能
### ✨ Features
- **git**: 修改提交逻辑 — 在createCommit函数中增加git add -A
- **chalk**: 替换kleur为chalk — 解决 Cannot read properties of undefined 报错
- 添加deploy add命令 — 支持向已有配置添加新环境
- 修复问题发布前检查清单
- [ ] 所有代码已提交到 git
- [ ]
npm run build编译成功 - [ ]
quick release npm --dry-run预览无异常 - [ ] npm 已登录（
npm whoami）
配置说明
完整配置示例
// .deployrc.js
export default {
envs: {
dev: {
name: 'my_project',
server: {
host: '${DEV_HOST}',
port: 22,
username: '${DEV_USER}',
password: '${DEV_PASSWORD}',
},
projectDir: 'C:/A_code/my_project',
distDir: 'dist',
build: {
cmd: 'npm run build-only',
skip: false,
packageManager: 'pnpm',
},
preCmd: '',
postCmd: '',
deploy: {
paths: [
{ remote: '/uinnova/testDeploy', description: '主站' },
],
},
backup: {
enabled: true,
remoteDir: '/uinnova/testDeploy/backups',
maxCount: 5,
format: '{name}_back_{YYYYMMDDHHmmss}',
},
},
prod: {
name: 'my_project_prod',
server: {
host: '${PROD_HOST}',
port: 22,
username: '${PROD_USER}',
privateKey: '${PROD_KEY_PATH}',
},
projectDir: 'C:/A_code/my_project',
distDir: 'dist',
build: { cmd: 'npm run build-only', skip: false, packageManager: 'pnpm' },
preCmd: 'pm2 stop prod-app',
deploy: { paths: [{ remote: '/uinnova/prod', description: '生产' }] },
backup: { enabled: true, remoteDir: '/uinnova/prod/backups', maxCount: 10, format: '{name}_back_{YYYYMMDDHHmmss}' },
postCmd: 'pm2 start prod-app',
},
},
defaults: {
compress: { enabled: true, level: 9 },
upload: { retryCount: 3, retryDelay: 1000 },
deploy: { interactive: false },
},
}配置字段速查
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 项目名称 |
| server.host | string | 服务器地址 |
| server.port | number | SSH 端口 |
| server.username | string | 用户名 |
| server.password | string | 密码（与 privateKey 二选一） |
| server.privateKey | string | 私钥路径（与 password 二选一） |
| projectDir | string | 本地项目路径 |
| distDir | string | 构建产物路径 |
| build.cmd | string | 构建命令 |
| build.skip | boolean | 跳过构建 |
| build.packageManager | string | npm / pnpm / yarn |
| preCmd | string | 上传前服务器命令 |
| deploy.paths[].remote | string | 远程部署路径 |
| deploy.paths[].description | string | 路径备注 |
| backup.enabled | boolean | 启用备份 |
| backup.remoteDir | string | 远程备份目录 |
| backup.maxCount | number | 最大保留备份数 |
| backup.format | string | 备份命名模板 |
| postCmd | string | 上传后服务器命令 |
备份命名模板
format: '{name}_back_{YYYYMMDDHHmmss}'
示例： my_project_back_20260430170949.tar.gz
部署流程
quick deploy env 构建与部署流程
1. 读取 .deployrc.js，定位 envConfig.projectDir 和 distDir
2. 检测包管理器（缺失则自动全局安装）
3. 检测 node_modules（缺失则自动 <pm> install）
4. 在 envConfig.projectDir 中执行 build.cmd
5. 生成 projectDir/.quick-release/build-log.json
6. 生成 projectDir/.quick-release/logs/build-YYYYMMDD-HHmmss.md
7. 只提交 .quick-release/build-log.json 和本次 Markdown 日志到业务项目 Git 仓库
8. 将日志 commit 推送到远程仓库
9. 复制构建日志到 distDir/.quick-release/**
10. 压缩构建产物 distDir (tar.gz)，此时 .quick-release 日志已进入部署包
11. 连接 SSH 服务器
12. 执行 preCmd
13. 备份当前版本 → 清理旧备份（保留 maxCount）
14. 上传压缩包 → 远程原子替换
15. 服务器部署目录保留 .quick-release/**
16. 执行 postCmd
17. 清理本地临时压缩包注意：deploy 构建日志提交/推送发生在
envConfig.projectDir对应的业务项目仓库中，不是 quick-fe-cli 工具仓库。
项目结构
quick-fe-cli/
├── src/
│ ├── index.ts # quick 主入口，注册 deploy / release / skill 命令组
│ ├── commands/
│ │ ├── deploy/ # 部署命令组
│ │ │ ├── deploy.ts # quick deploy <envs>
│ │ │ ├── rollback.ts # quick deploy rollback <env>
│ │ │ ├── init.ts # quick deploy init
│ │ │ ├── add.ts # quick deploy add [envName]
│ │ │ ├── list.ts # quick deploy list
│ │ │ └── backups.ts # quick deploy backups <env>
│ │ ├── release/ # 发布命令组
│ │ │ ├── release.ts # quick release 命令组入口
│ │ │ ├── build.ts # quick release build：构建、版本日志、版本号、commit/tag
│ │ │ └── npm.ts # quick release npm：发布当前版本到 npm
│ │ └── skill/ # Skill 命令组
│ │ ├── skill.ts # skill 命令组入口
│ │ ├── list.ts # quick skill list
│ │ ├── install.ts # quick skill install [name]
│ │ └── registry.ts # skill 注册表 + 平台配置
│ ├── core/ # 核心模块（共享）
│ │ ├── deploy.ts # 部署流水线；构建后复制 .quick-release 到 dist 并打包上传
│ │ ├── release/ # 发布与构建日志核心能力
│ │ │ ├── index.ts # release build 编排
│ │ │ ├── build.ts # 公共构建能力；生成/提交/推送 .quick-release 构建日志
│ │ │ ├── changelog.ts # CHANGELOG 和构建 Markdown 日志生成
│ │ │ ├── git.ts # Git commit / tag / push / 指定路径提交
│ │ │ ├── npm.ts # npm publish 封装
│ │ │ └── version.ts # 版本号、commit 分析、Git 日志读取
│ │ ├── ssh.ts # SSH 连接
│ │ ├── compress.ts # 压缩
│ │ ├── backup.ts # 备份 + 回滚 + 清理
│ │ ├── hooks.ts # 钩子引擎
│ │ ├── config.ts # 配置加载
│ │ └── logger.ts # 日志（chalk）
│ ├── types.ts # 类型定义
│ └── utils/
│ ├── format.ts # 格式化
│ ├── validate.ts # 校验
│ └── init-wizard.ts # 交互引导模块（init / add 共享）
├── docs/
│ └── release-deploy-build-log-requirements.md # 发布/部署构建日志完整需求文档
├── skills/ # 内置 Skill 定义
│ └── deploy/
│ └── SKILL.md # 前端部署 skill
├── scripts/ # 历史脚本，保留兼容参考
│ ├── version.ts # 旧版版本管理 + 提交分析
│ ├── changelog.ts # 旧版 CHANGELOG 生成
│ ├── git.ts # 旧版 Git 操作
│ └── release.ts # 旧版交互式发布主流程
├── .quick-release/ # 构建日志目录；release build 时在本仓库生成
│ ├── build-log.json # 最近一次构建结构化日志
│ └── logs/
│ └── build-YYYYMMDD-HHmmss.md # 每次构建对应的 Git 更新 Markdown 日志
├── .release-it.json # 历史 release-it 配置
├── .npmignore # npm 发布排除规则
├── package.json
├── tsconfig.json
├── CHANGELOG.md # release build 自动生成/更新
└── README.md被 quick deploy env 打包的业务项目会生成并提交如下结构：
业务项目/
├── .quick-release/
│ ├── build-log.json
│ └── logs/
│ └── build-YYYYMMDD-HHmmss.md
└── dist/
└── .quick-release/
├── build-log.json
└── logs/
└── build-YYYYMMDD-HHmmss.md其中业务项目根目录下的 .quick-release/** 会提交并推送到远程仓库，dist/.quick-release/** 只随部署包上传，不提交到 Git。
扩展新命令组
在 src/commands/ 下新建目录：
// src/commands/analyze/analyze.ts
import { Command } from 'commander';
export function createBundleAnalyzeCommand(): Command {
return new Command('bundle').description('分析打包体积').action(() => {
console.log('分析中...');
});
}
// src/index.ts
import { Command } from 'commander';
import { createBundleAnalyzeCommand } from './commands/analyze/analyze';
const analyzeGroup = new Command('analyze').description('代码分析');
analyzeGroup.addCommand(createBundleAnalyzeCommand());
program.addCommand(analyzeGroup);使用：quick analyze bundle
Skill 系统
为 AI 编码助手（Trae、Claude Code、OpenAI Codex）提供标准化的项目使用指南。
quick skill list # 查看可用 Skill
quick skill install # 交互式安装（选 Skill → 选平台 → 确认）
quick skill install deploy # 直接安装 deploy skill目标平台
| 平台 | 安装路径 |
|------|----------|
| Trae | .trae/skills/deploy/SKILL.md |
| Claude Code | .claude/skills/deploy/SKILL.md |
| OpenAI Codex | .codex/skills/deploy/SKILL.md |
安装效果
安装后，AI 编码助手会自动读取对应目录下的 SKILL.md 文件，获取项目的部署流程、配置说明和使用指南，从而更好地辅助开发。
环境变量
# .env
DEV_HOST=192.168.1.100
DEV_USER=root
DEV_PASSWORD=your_passwordLicense
MIT