SZHN CLI — 前端项目脚手架

szhn-cli 是数字海南前端项目脚手架工具，支持通过命令行或可视化 UI 快速创建标准化前端工程。

执行步骤

步骤 1：检查并安装 CLI

检查是否已安装：

szhn-cli --version

若未安装，先配置私有源后安装：

npm config set registry https://npmmirror.digitalhainan.com.cn/
npm install -g @szhn/szhn-cli

若已安装，建议更新到最新版：

npm update -g @szhn/szhn-cli

---

步骤 2：创建项目

方式一：命令行模式（推荐）

szhn-cli init <项目名称>

若不带项目名，CLI 会询问是否在当前目录初始化：

szhn-cli init

方式二：可视化 UI 模式

szhn-cli ui

启动本地 Web 界面，功能与命令行一致，体验更直观。

---

步骤 3：回答交互问题

执行 init 后，CLI 会依次询问以下信息：

问题	说明	默认值
选择项目模板	见下方模板列表，默认推荐 PC Admin Web 单应用版本（Vue 3）	—
项目名称	生成的目录名	命令行传入的名称
项目描述	写入 package.json	A project named {name}
版本号	写入 package.json	0.0.1
作者	写入 package.json	—
平台名称	仅 element / PC 模板可见，写入页面标题	后台管理系统
baseApi	请求基础路径，写入代理与接口配置	/base-api
本地代理地址	开发时的接口代理目标	https://onecode-app-dev.digitalhainan.com.cn
是否开启埋点	是否注入埋点插件	是

部分问题仅在所选模板支持对应属性时才会显示。

---

支持的项目模板

模板名称	类型	技术栈	额外配置项
PC Admin Web 单应用版本（集成海政通、UAA，适合大多数项目） ✅ 默认推荐	PC 后台	Vue 3	—
PC Admin Web Monorepo 版本（集成海政通、UAA，适合大项目多子应用）	PC 后台	Vue 3	—
H5 Web	移动端 H5	Vue 3	—
H5 Miniprogram	小程序/H5	Vue 3	baseApi、本地代理、埋点
PC Admin Web（集成海政通）	PC 后台	Vue 2	baseApi、本地代理、埋点
PC Admin Web	PC 后台	Vue 2	平台名称、baseApi、本地代理、埋点
H5 Web（集成海政通）	移动端 H5	Vue 2	baseApi、本地代理、埋点
H5 Web	移动端 H5	Vue 2	baseApi、本地代理、埋点
H5 Waterbear	移动端 H5	Vue 2	baseApi、本地代理、埋点
SDK 类库通用模版	类库	JS	—

实际模板列表由远程配置动态下发，可能随版本更新增减。

---

项目初始化完成后的操作

CLI 完成模板克隆后，会自动：

1. 将项目信息写入 package.json（name、description、version、author）
2. 写入 baseApi 配置（接口请求基础路径）
3. 写入本地开发代理配置（vue.config.js / vite.config.js）
4. 对 element / PC 模板写入平台名称（页面标题）
5. 若选择开启埋点，注入埋点插件

随后询问是否全局安装 @szhn/ai-cli（AI 辅助开发工具），建议安装。

进入项目目录后正常启动：

cd <项目名称>
pnpm install
npm run dev

若未安装 pnpm，可使用 npm install 替代。

---

常见问题

常见问题

问题	原因	解决方案
模板下载失败	SSH 未配置或网络不通	检查 SSH key 是否添加至 GitLab；确认可访问 gitlab.digitalhainan.com.cn
szhn-cli 命令不存在	未全局安装	执行 npm install -g @szhn/szhn-cli
项目已存在提示	同名目录已存在	CLI 会询问是否删除，确认后重新创建
接口请求 404	Vite 代理配置未指向本地后端	修改 vite.config.mts 中的 proxy.target 为本地后端地址

---

Vite 代理配置指南

创建项目后，需要修改 vite.config.mts 中的代理配置以指向本地后端服务：

默认配置（指向远程环境）

server: {
  host: true,
  port: 5555,
  proxy: {
    '/admin-web/api': {
      changeOrigin: true,
      rewrite: (path: string) => path.replace(/^\/admin-web\/api/, ''),
      target: 'https://system-manage-dev.digitalhainan.com.cn/system-manage/api',
      ws: true,
    },
  },
},

本地开发配置（指向本地后端）

修改 target 为本地后端地址：

server: {
  host: true,
  port: 5555,
  proxy: {
    '/admin-web/api': {
      changeOrigin: true,
      rewrite: (path: string) => path.replace(/^\/admin-web\/api/, ''),
      target: 'http://localhost:8081/<context-path>/api',  // 修改为本地后端地址
      ws: true,
    },
  },
},

配置说明

配置项	说明
/admin-web/api	前端请求的基础路径前缀
rewrite	重写规则，移除路径前缀后转发到后端
target	后端服务地址，本地开发修改为 http://localhost:{后端端口}/{context-path}
changeOrigin	修改请求头中的 host 为目标地址
ws	是否支持 WebSocket

示例

如果后端配置为：

• 端口：8081
• context-path：/<context-path>

则 Vite 代理配置应为：

target: 'http://localhost:8081/<context-path>'