ylyx-cli 1.0.15 → 1.1.0

package/README.md

@@ -1,276 +1,313 @@
-# YLYX CLI - 项目脚手架工具
-
-公司内部使用的项目脚手架工具：支持交互式/命令式生成项目与代码模板，并提供 `.ylyxrc.json` 项目配置、环境配置切换（`isDev`）、以及一键部署（测试服上传/正式服打包压缩）等能力。
-
-> 说明：当前部署/配置切换能力**暂时只针对 Vue2 项目约定**（如 `.env.production` 的 `VUE_APP_PUBLIC_URL` 等）。其它技术栈/项目结构可能需要你根据实际情况调整 `.ylyxrc.json` 与相关路径配置。
-
-## 功能特性
-
-- 🚀 **快速生成项目代码**：内置多种模板，一键生成项目/组件/模块代码
-- 📦 **模板化管理**：模板目录结构清晰，易维护、易扩展；支持本地模板添加
-- ☁️ **云端模板**：支持从 GitHub/GitLab 仓库安装模板（含私有仓库 SSH 场景）
-- 📝 **交互式命令行**：`create` 支持交互式收集变量，降低使用门槛
-- ⚙️ **项目配置（.ylyxrc.json）**：集中管理模板目录、输出目录、构建目录等配置
-- 🔁 **环境配置切换（isDev）**：提供 `ylyx config dev|prod`，自动同步/复制 `default.js`
-- 🧰 **初始化配置（init config）**：自动生成 `.ylyxrc.json`、`config/default-*.js`，并可写入 npm 前/后置脚本
-- 🚚 **部署（deploy）**：支持测试服（SFTP 上传，带上传进度）与正式服（仅压缩）两种模式，压缩包命名/顶层目录规则与 `buildDir` 对齐
-
-## 安装
-
-### 全局安装
-
-```bash
-npm install -g ylyx-cli
-```
-
-### 使用 npx（推荐，无需安装）
-
-```bash
-# 使用 npx 直接运行
-npx ylyx-cli create
-
-# 生成项目
-npx ylyx-cli generate react-app -n my-project -o ./my-project
-
-# 安装远程模板
-npx ylyx-cli install owner/repo
-```
-
-### 本地开发
-
-```bash
-git clone <repository>
-cd ylyx-cli
-npm install
-npm link  # 链接到全局，可以本地测试
-```
-
-## 使用方法
-
-### 快速开始
-
-使用交互式方式创建新项目（推荐）：
-
-```bash
-ylyx create
-```
-
-或者直接指定模板和项目名：
-
-```bash
-# 创建一个 React 项目
-ylyx generate react-app -n my-project -o ./my-project
-```
-
-### 查看可用模板
-
-```bash
-ylyx list
-```
-
-### 安装远程模板
-
-从 GitHub/GitLab 安装模板：
-
-```bash
-# 使用简写格式（GitHub）
-ylyx install owner/repo
-
-# 使用完整 URL
-ylyx install https://github.com/owner/repo
-
-# 指定分支和模板名
-ylyx install owner/repo -b develop -n my-template
-```
-
-### 添加本地模板
-
-```bash
-ylyx add template-name /path/to/template
-```
-
-### 查看模板详情
-
-```bash
-ylyx info template-name
-```
-
-### 写入配置（mode）
-
-将当前目录的 `.ylyxrc.json` 写入/更新 `mode`（仅支持 `dev` / `prod`）：
-
-```bash
-ylyx config --mode dev
-# 或
-ylyx config prod
-```
-
-### 初始化配置（init config）
-
-初始化当前目录的配置文件与默认配置模板（会生成/补齐 `.ylyxrc.json`，并创建 `config/default-dev.js`、`config/default-prod.js` 等；默认不覆盖已有文件）：
-
-```bash
-ylyx init config
-
-# 指定初始模式
-ylyx init config --mode prod
-
-# 强制覆盖已存在文件
-ylyx init config --force
-```
-
-`init config` 还会尝试在当前目录的 `package.json` 中写入 npm 前置脚本（可在 `.ylyxrc.json` 的 `preScripts` 配置脚本名）：
-
-- 默认会写入 `predev` 和 `postbuild:prod`
-- 执行 `npm run dev` 前，会自动先执行 `ylyx config dev`（dev 使用 symlink 实时同步）
-- 执行 `npm run build:prod` 后，会自动执行 `ylyx config prod && ylyx deploy`（将 `default-prod.js` 复制到打包输出目录，并执行部署）
-
-prod 输出目录规则：
-
-- 优先使用 `.ylyxrc.json` 的 `buildDir`
-- 否则读取当前项目 `.env.production` 的 `VUE_APP_PUBLIC_URL`，默认写入 `<VUE_APP_PUBLIC_URL>/default.js`（会去掉首尾 `/`）
-
-## deploy（部署）
-
-`deploy` 会读取当前项目目录的 `.ylyxrc.json` 的 `deploy` 字段。
-
-### 配置示例（.ylyxrc.json）
-
-```json
-{
-  "mode": "dev",
-  "buildDir": "dist/app",
-  "deploy": {
-    "env": "test",
-    "host": "172.17.28.216",
-    "port": "22",
-    "username": "root",
-    "password": "你的密码",
-    "localDir": "./EXTERNAL_DIGIC",
-    "remoteDir": "/usr/local/nginx/html/EXTERNAL_DIGIC",
-    "zipAfter": false,
-    "zipOutDir": "./.ylyx-deploy"
-  }
-}
-```
-
-### 行为
-
-- 测试服：SFTP 递归上传到服务器（带上传进度）
-- 正式服：不上传，仅压缩
-
-压缩产物命名规则（正式服或 `--zip`）：`buildDir(最后一级)-YYYYMMDDHHmmss-哈希(纯字母).zip`，且 zip 内顶层目录名为 `buildDir` 的最后一级目录名。
-
-`localDir` 默认推导优先级：`deploy.localDir` → `.env.production` 的 `VUE_APP_PUBLIC_URL` → `.ylyxrc.json` 的 `buildDir`。
-
-### 上传日志
-
-每次执行 `deploy` 会在本地生成一份日志，默认在 `./.ylyx-deploy/logs/`，包含上传/压缩过程与错误信息，便于追溯。
-
-### 命令
-
-```bash
-ylyx deploy
-ylyx deploy --env test
-ylyx deploy --env prod
-```
-
-## 云端模板
-
-模板可以放在 Git 仓库中（如 GitHub、GitLab），使用 `ylyx install` 命令安装。
-
-### 模板仓库要求
-
-模板仓库需要包含以下结构：
-
-```
-your-template/
-  template.json      # 模板配置文件（可选）
-  files/            # 模板文件目录
-    ...
-```
-
-### 示例
-
-```bash
-# 从 GitHub 安装模板
-ylyx install github-user/react-template
-
-# 从私有仓库安装（需要配置 SSH 密钥）
-ylyx install git@github.com:company/templates.git
-
-# 指定分支
-ylyx install owner/repo -b v2.0
-```
-
-## 模板配置
-
-模板应放在 `templates/` 目录下，结构如下：
-
-```
-templates/
-  template-name/
-    template.json      # 模板配置文件
-    files/            # 模板文件目录
-      example.js
-      example.css
-```
-
-### template.json 配置示例
-
-```json
-{
-	"name": "template-name",
-	"description": "模板描述",
-	"version": "1.0.0",
-	"variables": {
-		"projectName": {
-			"type": "input",
-			"message": "请输入项目名称",
-			"default": "my-project"
-		}
-	},
-	"processFiles": ["package.json", "README.md", "*.json"],
-	"skipFiles": ["**/*.vue", "**/*.js"]
-}
-```
-
-## 配置文件
-
-可以在项目根目录创建 `.ylyxrc.json` 配置文件：
-
-```json
-{
-	"mode": "dev",
-	"publicDir": "./public",
-	"configDir": "./config",
-	"preScripts": {
-		"dev": "dev",
-		"prod": "build:prod"
-	},
-	"templatesDir": "./templates",
-	"outputDir": "./src",
-	"defaultVariables": {
-		"author": "Your Name",
-		"company": "YLYX"
-	}
-}
-```
-
-## 示例
-
-### 生成完整项目
-
-```bash
-# 生成 React 项目
-ylyx generate react-app -n my-react-app -o ./my-react-app
-
-# 生成后进入目录并安装依赖
-cd my-react-app
-npm install
-npm start
-```
-
-## License
-
-ISC
+# YLYX CLI - 项目脚手架工具
+
+公司内部使用的项目脚手架工具：支持交互式/命令式生成项目与代码模板，并提供 `.ylyxrc.json` 项目配置、支持任意数量的自定义环境切换（dev/test/staging/prod...），以及一键部署（SFTP 上传/仅压缩）等能力。
+
+> 说明：每个环境需要在 `.ylyxrc.json` 中显式配置 `buildDir` 等路径信息（不再从 `.env.production` 自动推导）。
+
+## 功能特性
+
+- 🚀 **快速生成项目代码**：内置多种模板，一键生成项目/组件/模块代码
+- 📦 **模板化管理**：模板目录结构清晰，易维护、易扩展；支持本地模板添加
+- ☁️ **云端模板**：支持从 GitHub/GitLab 仓库安装模板（含私有仓库 SSH 场景）
+- 📝 **交互式命令行**：`create` 支持交互式收集变量，降低使用门槛
+- ⚙️ **项目配置（.ylyxrc.json）**：集中管理模板目录、输出目录、构建目录等配置
+- 🔁 **多环境配置切换**：`.ylyxrc.json` 的 `environments` 支持任意数量的自定义环境（dev/test/staging/prod...），`ylyx config <name>` 一键切换
+- 🧰 **初始化配置（init config）**：自动生成 `.ylyxrc.json`、`config/default-*.js`，并可写入 npm 前/后置脚本
+- 🚚 **部署（deploy）**：按环境 `deployMethod` 决定上传（SFTP，带上传进度）或仅压缩，压缩包命名/顶层目录规则与该环境 `buildDir` 对齐
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g ylyx-cli
+```
+
+### 使用 npx（推荐，无需安装）
+
+```bash
+# 使用 npx 直接运行
+npx ylyx-cli create
+
+# 生成项目
+npx ylyx-cli generate react-app -n my-project -o ./my-project
+
+# 安装远程模板
+npx ylyx-cli install owner/repo
+```
+
+### 本地开发
+
+```bash
+git clone <repository>
+cd ylyx-cli
+npm install
+npm link  # 链接到全局，可以本地测试
+```
+
+## 使用方法
+
+### 快速开始
+
+使用交互式方式创建新项目（推荐）：
+
+```bash
+ylyx create
+```
+
+或者直接指定模板和项目名：
+
+```bash
+# 创建一个 React 项目
+ylyx generate react-app -n my-project -o ./my-project
+```
+
+### 查看可用模板
+
+```bash
+ylyx list
+```
+
+### 安装远程模板
+
+从 GitHub/GitLab 安装模板：
+
+```bash
+# 使用简写格式（GitHub）
+ylyx install owner/repo
+
+# 使用完整 URL
+ylyx install https://github.com/owner/repo
+
+# 指定分支和模板名
+ylyx install owner/repo -b develop -n my-template
+```
+
+### 添加本地模板
+
+```bash
+ylyx add template-name /path/to/template
+```
+
+### 查看模板详情
+
+```bash
+ylyx info template-name
+```
+
+### 切换环境（config）
+
+将当前目录的 `.ylyxrc.json` 切换到指定环境（环境名来自 `.ylyxrc.json` 的 `environments` 数组，可以是任意自定义名字）：
+
+```bash
+ylyx config dev
+ylyx config prod
+ylyx config staging
+```
+
+不传参数时进入交互式选择（按本地/部署环境分组，当前环境标注"（当前）"，默认光标停在当前环境）：
+
+```bash
+ylyx config
+```
+
+若 `.ylyxrc.json` 是旧版格式（没有 `configVersion`），命令会报错并提示先运行：
+
+```bash
+ylyx migrate config
+```
+
+### 初始化配置（init config）
+
+初始化当前目录的配置文件与默认配置模板（会生成/补齐 `.ylyxrc.json`，并为每个环境创建 `config/default-<name>.js`；默认不覆盖已有文件）：
+
+```bash
+ylyx init config
+
+# 指定初始 currentEnv
+ylyx init config --env prod
+
+# 强制覆盖已存在文件
+ylyx init config --force
+```
+
+新项目默认生成两个环境：`dev`（本地开发，`isLocal:true`）和 `prod`（`deployMethod:'zip'`，`buildDir:'dist/app'`）。如果需要 `test`/`staging` 等更多环境，在 `.ylyxrc.json` 的 `environments` 数组里手动追加后，重新运行 `ylyx init config --force` 补写对应的 `config/default-<name>.js` 和 npm 钩子。
+
+`init config` 会根据每个环境的 `npmScript` 字段，在当前目录的 `package.json` 中写入 npm 钩子：
+
+- `isLocal: true` 的环境（如 dev）→ 写入 `pre<npmScript>: "ylyx config <name>"`
+- 其他环境（如 prod）→ 写入 `post<npmScript>`，若该环境 `deployMethod` 不是 `none`，值为 `"ylyx config <name> && ylyx deploy --env <name>"`，否则只是 `"ylyx config <name>"`
+
+每个环境的构建输出目录由该环境条目的 `buildDir` 字段决定，需要显式配置。
+
+## deploy（部署）
+
+`deploy` 会读取当前项目目录的 `.ylyxrc.json` 的 `environments` 数组，按 `--env <name>` 指定的环境读取对应字段。
+
+### 配置示例（.ylyxrc.json）
+
+```json
+{
+  "configVersion": 2,
+  "publicDir": "./public",
+  "configDir": "./config",
+  "currentEnv": "dev",
+  "environments": [
+    { "name": "dev", "isLocal": true, "npmScript": "dev", "deployMethod": "none" },
+    {
+      "name": "test",
+      "npmScript": "build:test",
+      "deployMethod": "upload",
+      "buildDir": "dist/test",
+      "host": "172.17.28.216",
+      "port": "22",
+      "username": "root",
+      "password": "你的密码",
+      "localDir": "./dist/test",
+      "remoteDir": "/usr/local/nginx/html/TEST_APP",
+      "zipAfter": false
+    },
+    {
+      "name": "prod",
+      "npmScript": "build:prod",
+      "deployMethod": "zip",
+      "buildDir": "dist/app",
+      "zipOutDir": "./.ylyx-deploy"
+    }
+  ]
+}
+```
+
+### 行为
+
+- `deployMethod: 'upload'` 的环境：SFTP 递归上传到服务器（带上传进度）
+- `deployMethod: 'zip'` 的环境：不上传，仅压缩
+- `deployMethod: 'none'` 的环境：不可部署
+
+压缩产物命名规则：`buildDir(最后一级)-YYYYMMDDHHmmss-哈希(纯字母).zip`，且 zip 内顶层目录名为 `buildDir` 的最后一级目录名。
+
+`localDir` 缺省时使用该环境的 `buildDir`；不再支持从 `.env.production` 自动推导，需要显式配置。
+
+### 从旧版配置迁移
+
+如果 `.ylyxrc.json` 还是旧格式（`mode`/`deploy`/顶层 `buildDir`），运行：
+
+```bash
+ylyx migrate config
+```
+
+会自动生成 `dev`（本地开发）、`test`（SFTP 上传）、`prod`（仅压缩）三个环境，并删除旧的 `mode`/`deploy`/`buildDir`/`preScripts` 字段。迁移后请检查 `test`/`prod` 环境里的 `host`/`username`/`password` 等敏感信息，并按需运行 `ylyx init config --force` 补写 `package.json` 的部署钩子。
+
+### 上传日志
+
+每次执行 `deploy` 会在本地生成一份日志，默认在 `./.ylyx-deploy/logs/`，包含上传/压缩过程与错误信息，便于追溯。
+
+### 命令
+
+```bash
+ylyx deploy
+ylyx deploy --env test
+ylyx deploy --env prod
+ylyx deploy --env staging
+```
+
+## 云端模板
+
+模板可以放在 Git 仓库中（如 GitHub、GitLab），使用 `ylyx install` 命令安装。
+
+### 模板仓库要求
+
+模板仓库需要包含以下结构：
+
+```
+your-template/
+  template.json      # 模板配置文件（可选）
+  files/            # 模板文件目录
+    ...
+```
+
+### 示例
+
+```bash
+# 从 GitHub 安装模板
+ylyx install github-user/react-template
+
+# 从私有仓库安装（需要配置 SSH 密钥）
+ylyx install git@github.com:company/templates.git
+
+# 指定分支
+ylyx install owner/repo -b v2.0
+```
+
+## 模板配置
+
+模板应放在 `templates/` 目录下，结构如下：
+
+```
+templates/
+  template-name/
+    template.json      # 模板配置文件
+    files/            # 模板文件目录
+      example.js
+      example.css
+```
+
+### template.json 配置示例
+
+```json
+{
+	"name": "template-name",
+	"description": "模板描述",
+	"version": "1.0.0",
+	"variables": {
+		"projectName": {
+			"type": "input",
+			"message": "请输入项目名称",
+			"default": "my-project"
+		}
+	},
+	"processFiles": ["package.json", "README.md", "*.json"],
+	"skipFiles": ["**/*.vue", "**/*.js"]
+}
+```
+
+## 配置文件
+
+可以在项目根目录创建 `.ylyxrc.json` 配置文件：
+
+```json
+{
+	"configVersion": 2,
+	"currentEnv": "dev",
+	"publicDir": "./public",
+	"configDir": "./config",
+	"environments": [
+		{ "name": "dev", "isLocal": true, "npmScript": "dev", "deployMethod": "none" },
+		{ "name": "prod", "npmScript": "build:prod", "deployMethod": "zip", "buildDir": "dist/app" }
+	],
+	"templatesDir": "./templates",
+	"outputDir": "./src",
+	"defaultVariables": {
+		"author": "Your Name",
+		"company": "YLYX"
+	}
+}
+```
+
+## 示例
+
+### 生成完整项目
+
+```bash
+# 生成 React 项目
+ylyx generate react-app -n my-react-app -o ./my-react-app
+
+# 生成后进入目录并安装依赖
+cd my-react-app
+npm install
+npm start
+```
+
+## License
+
+ISC