@quicktvui/web-cli v3

QuickTVUI Web 开发服务器 CLI 工具，v3 采用委托构建 + Bundle 加载模式。

v3 架构说明

| 项 | 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 等 | 无（大幅简化） |

安装

npm install @quicktvui/web-cli@3 --save-dev
# 或
yarn add @quicktvui/web-cli@3 --dev
# 或
pnpm add @quicktvui/web-cli@3 -D

前置要求

项目需要在 package.json 中配置 dev 脚本，使用 qt-dev 构建到 dist/dev/ 目录：

{
  "scripts": {
    "dev": "qt-dev android -c ./scripts/quicktvui-webpack.dev.ts"
  }
}

dev 脚本的 webpack 配置需要输出 index.bundle 到 dist/dev/ 目录。

使用

基本用法

# 在项目目录下运行
npx qt-web-cli

# 或在 package.json 中添加脚本
{
  "scripts": {
    "web:dev": "qt-web-cli"
  }
}

命令行选项

用法: qt-web-cli [options]

选项:
  -p, --port <port>         开发服务器端口 (默认: 39001)
  -o, --open                自动打开浏览器
  -h, --help                显示帮助信息
  -v, --version             显示 CLI 版本
  --info                    显示 CLI 和 web-runtime 版本
  --dev-script <name>       指定要运行的 npm script (默认: dev)
  --dist-dir <path>         指定构建产物目录 (默认: dist/dev)
  --no-auto-build           跳过自动调用 dev 脚本，仅启动服务器
  --v1                      已移除，仅保留参数兼容提示

使用场景

1. 自动构建 + 启动（默认）

qt-web-cli
# 自动调用 npm run dev，构建完成后启动服务器

2. 仅启动服务器（已有构建产物）

qt-web-cli --no-auto-build
# 不调用 npm run dev，仅启动静态服务器
# 需要手动在其他终端运行 npm run dev

3. 指定其他构建脚本

qt-web-cli --dev-script build
# 使用 npm run build 替代 npm run dev

4. --v1 兼容提示

qt-web-cli --v1
# 提示 v1 已移除，请使用默认 web-runtime 模式

工作流程

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 通知浏览器刷新

构建产物结构

dist/dev/
  ├── index.bundle                          # 主入口
  ├── src_views_xxx_vue.index.bundle        # 按路由分包
  └── assets/                               # 静态资源

内置功能

自动代理

CLI 内置代理功能，解决开发环境跨域问题：

/proxy/{protocol}/{host}{path}

示例:
/proxy/https/api.example.com/users
  -> https://api.example.com/users

SSE 热更新

v2 使用 SSE (Server-Sent Events) 实现热更新：

• 监听 dist/dev/ 目录变化
• 文件变化时通知浏览器自动刷新
• 状态栏显示构建状态

迁移指南 (v1 → v2)

从 v1 迁移

1. 确保项目有 dev 脚本配置
2. 确保 dev 脚本输出到 dist/dev/ 目录
3. 确保 webpack 输出文件名为 index.bundle
4. 升级 @quicktvui/web-cli 到 v2
5. 移除不再需要的 webpack peerDependencies

典型的 webpack dev 配置

// scripts/quicktvui-webpack.dev.ts
module.exports = {
  output: {
    filename: 'index.bundle',
    path: path.resolve(__dirname, '../dist/dev/'),
  },
  // ... 其他配置
}

License

Apache-2.0