@quicktvui/web-cli

QuickTVUI Web 开发服务器 CLI 工具，零配置启动 Web 渲染开发环境。

安装

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

使用

基本用法

# 安装后直接运行
npx qt-web-dev

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

命令行选项

用法: qt-web-dev [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

入口文件检测规则

CLI 会自动检测项目入口，优先级如下：

1. webMain 配置（推荐）

如果 package.json 中配置了 webMain，直接使用该入口：

{
  "main": "./src/main.ts",
  "webMain": "./src/main-web.js"
}

2. 本地 src/web 目录

如果没有 webMain 但存在 src/web/index.js，CLI 会：

• 使用 src/web 目录作为 Web 渲染器
• 自动包装 main 指定的入口文件

3. @quicktvui/web-renderer 包

如果以上都不满足，CLI 会：

• 使用 @quicktvui/web-renderer 包作为渲染器
• 自动包装 main 指定的入口文件

项目结构示例

方式一：独立 webMain 入口（推荐）

project/
├── package.json        # 配置 webMain
├── src/
│   ├── main.ts         # 原生入口
│   ├── main-web.js     # Web 入口（自定义初始化逻辑）
│   └── web/            # Web 渲染器
│       ├── index.js
│       ├── core/
│       └── components/
└── ...

// package.json
{
  "main": "./src/main.ts",
  "webMain": "./src/main-web.js"
}

方式二：零配置模式

project/
├── package.json        # 无需配置 webMain
├── src/
│   ├── main.ts         # 主入口
│   └── web/            # Web 渲染器（CLI 自动检测）
│       ├── index.js
│       └── core/
└── ...

方式三：使用 web-renderer 包

project/
├── package.json
├── src/
│   └── main.ts         # 主入口
└── ...

// package.json
{
  "dependencies": {
    "@quicktvui/web-renderer": "^1.0.0"
  }
}

内置功能

自动代理

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

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

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

自动检测路径别名

自动读取 jsconfig.json 或 tsconfig.json 中的路径配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

OpenSSL 兼容

自动检测 OpenSSL 版本，对于 OpenSSL 3.x 自动添加 --openssl-legacy-provider 参数。

自定义 Webpack 配置

如需自定义配置，可通过 --config 指定：

qt-web-dev --config ./webpack.config.js

自定义配置会完全替换内置配置。

技术栈

• Vue 3 + TypeScript
• Webpack 5
• vue-loader
• @extscreen/es3-vue-css-loader

License

MIT