@quicktvui/web-cli 1.0.8 → 2.1.0

package/README.md

@@ -1,29 +1,54 @@
-# @quicktvui/web-cli
+# @quicktvui/web-cli v2
 
-QuickTVUI Web 开发服务器 CLI 工具，零配置启动 Web 渲染开发环境。
+QuickTVUI Web 开发服务器 CLI 工具，v2 采用委托构建 + Bundle 加载模式。
+
+## v2 架构变化
+
+| 项 | v1 | v2 |
+|---|---|---|
+| 构建方式 | CLI 自带 webpack 构建 | 委托项目 `dev` 脚本构建 |
+| 入口检测 | 扫描 src/main*.ts | 读取 package.json scripts.dev |
+| 产物位置 | dist/web/ | dist/dev/ |
+| 服务器 | webpack-dev-server | 轻量静态服务器 |
+| 热更新 | webpack HMR | SSE + 页面刷新 |
+| peerDeps | webpack, vue-loader 等 | **无**（大幅简化） |
 
 ## 安装
 
 ```bash
-npm install @quicktvui/web-cli --save-dev
+npm install @quicktvui/web-cli@2 --save-dev
 # 或
-yarn add @quicktvui/web-cli --dev
+yarn add @quicktvui/web-cli@2 --dev
 # 或
-pnpm add @quicktvui/web-cli -D
+pnpm add @quicktvui/web-cli@2 -D
 ```
 
+## 前置要求
+
+项目需要在 `package.json` 中配置 `dev` 脚本，使用 `qt-dev` 构建到 `dist/dev/` 目录：
+
+```json
+{
+  "scripts": {
+    "dev": "qt-dev android -c ./scripts/quicktvui-webpack.dev.ts"
+  }
+}
+```
+
+`dev` 脚本的 webpack 配置需要输出 `index.bundle` 到 `dist/dev/` 目录。
+
 ## 使用
 
 ### 基本用法
 
 ```bash
-# 安装后直接运行
-npx qt-web-dev
+# 在项目目录下运行
+npx qt-web-cli
 
 # 或在 package.json 中添加脚本
 {
   "scripts": {
-    "web:dev": "qt-web-dev"
+    "web:dev": "qt-web-cli"
   }
 }
 ```
@@ -31,102 +56,72 @@ npx qt-web-dev
 ### 命令行选项
 
 ```
-用法: qt-web-dev [options]
+用法: qt-web-cli [options]
 
 选项:
-  -p, --port <port>     开发服务器端口 (默认: 39001)
-  -c, --config <path>   自定义 webpack 配置文件路径
-  -o, --open            自动打开浏览器
-  -h, --help            显示帮助信息
-
-示例:
-  qt-web-dev
-  qt-web-dev --port 8080
-  qt-web-dev --config ./my.webpack.js
+  -p, --port <port>         开发服务器端口 (默认: 39001)
+  -o, --open                自动打开浏览器
+  -h, --help                显示帮助信息
+  -v, --version             显示 CLI 版本
+  --info                    显示 CLI 和 web-renderer 版本
+  --dev-script <name>       指定要运行的 npm script (默认: dev)
+  --dist-dir <path>         指定构建产物目录 (默认: dist/dev)
+  --no-auto-build           跳过自动调用 dev 脚本，仅启动服务器
+  --v1                      使用 v1 模式 (webpack 自构建，已废弃)
 ```
 
-## 入口文件检测规则
-
-CLI 会自动检测项目入口，优先级如下：
-
-### 1. webMain 配置（推荐）
+### 使用场景
 
-如果 `package.json` 中配置了 `webMain`，直接使用该入口：
+#### 1. 自动构建 + 启动（默认）
 
-```json
-{
-  "main": "./src/main.ts",
-  "webMain": "./src/main-web.js"
-}
+```bash
+qt-web-cli
+# 自动调用 npm run dev，构建完成后启动服务器
 ```
 
-### 2. 本地 src/web 目录
-
-如果没有 `webMain` 但存在 `src/web/index.js`，CLI 会：
-- 使用 `src/web` 目录作为 Web 渲染器
-- 自动包装 `main` 指定的入口文件
-
-### 3. @quicktvui/web-renderer 包
+#### 2. 仅启动服务器（已有构建产物）
 
-如果以上都不满足，CLI 会：
-- 使用 `@quicktvui/web-renderer` 包作为渲染器
-- 自动包装 `main` 指定的入口文件
-
-## 项目结构示例
+```bash
+qt-web-cli --no-auto-build
+# 不调用 npm run dev，仅启动静态服务器
+# 需要手动在其他终端运行 npm run dev
+```
 
-### 方式一：独立 webMain 入口（推荐）
+#### 3. 指定其他构建脚本
 
-```
-project/
-├── package.json        # 配置 webMain
-├── src/
-│   ├── main.ts         # 原生入口
-│   ├── main-web.js     # Web 入口（自定义初始化逻辑）
-│   └── web/            # Web 渲染器
-│       ├── index.js
-│       ├── core/
-│       └── components/
-└── ...
+```bash
+qt-web-cli --dev-script build
+# 使用 npm run build 替代 npm run dev
 ```
 
-```json
-// package.json
-{
-  "main": "./src/main.ts",
-  "webMain": "./src/main-web.js"
-}
+#### 4. 使用 v1 模式
+
+```bash
+qt-web-cli --v1
+# 回退到 v1 模式（webpack 自构建），已废弃
 ```
 
-### 方式二：零配置模式
+## 工作流程
 
 ```
-project/
-├── package.json        # 无需配置 webMain
-├── src/
-│   ├── main.ts         # 主入口
-│   └── web/            # Web 渲染器（CLI 自动检测）
-│       ├── index.js
-│       └── core/
-└── ...
+1. 检测项目的 dev 脚本
+2. 检查 dist/dev/index.bundle 是否已存在
+   → 存在：跳过构建，直接启动服务器
+   → 不存在：调用 npm run dev 启动构建
+3. 启动轻量静态服务器
+   → 托管 dist/dev/ 目录
+   → 提供 web-runtime HTML 页面
+4. 浏览器打开 → 通过 web-runtime 加载 dist/dev/index.bundle
+5. 监听 dist/dev/ 文件变化 → SSE 通知浏览器刷新
 ```
 
-### 方式三：使用 web-renderer 包
+## 构建产物结构
 
 ```
-project/
-├── package.json
-├── src/
-│   └── main.ts         # 主入口
-└── ...
-```
-
-```json
-// package.json
-{
-  "dependencies": {
-    "@quicktvui/web-renderer": "^1.0.0"
-  }
-}
+dist/dev/
+  ├── index.bundle                          # 主入口
+  ├── src_views_xxx_vue.index.bundle        # 按路由分包
+  └── assets/                               # 静态资源
 ```
 
 ## 内置功能
@@ -143,43 +138,36 @@ CLI 内置代理功能，解决开发环境跨域问题：
   -> https://api.example.com/users
 ```
 
-### 自动检测路径别名
-
-自动读取 `jsconfig.json` 或 `tsconfig.json` 中的路径配置：
+### SSE 热更新
 
-```json
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"],
-      "@components/*": ["src/components/*"]
-    }
-  }
-}
-```
+v2 使用 SSE (Server-Sent Events) 实现热更新：
+- 监听 `dist/dev/` 目录变化
+- 文件变化时通知浏览器自动刷新
+- 状态栏显示构建状态
 
-### OpenSSL 兼容
+## 迁移指南 (v1 → v2)
 
-自动检测 OpenSSL 版本，对于 OpenSSL 3.x 自动添加 `--openssl-legacy-provider` 参数。
+### 从 v1 迁移
 
-## 自定义 Webpack 配置
+1. 确保项目有 `dev` 脚本配置
+2. 确保 `dev` 脚本输出到 `dist/dev/` 目录
+3. 确保 webpack 输出文件名为 `index.bundle`
+4. 升级 `@quicktvui/web-cli` 到 v2
+5. 移除不再需要的 webpack peerDependencies
 
-如需自定义配置，可通过 `--config` 指定：
+### 典型的 webpack dev 配置
 
-```bash
-qt-web-dev --config ./webpack.config.js
+```js
+// scripts/quicktvui-webpack.dev.ts
+module.exports = {
+  output: {
+    filename: 'index.bundle',
+    path: path.resolve(__dirname, '../dist/dev/'),
+  },
+  // ... 其他配置
+}
 ```
 
-自定义配置会完全替换内置配置。
-
-## 技术栈
-
-- Vue 3 + TypeScript
-- Webpack 5
-- vue-loader
-- @extscreen/es3-vue-css-loader
-
 ## License
 
-MIT
+Apache-2.0