一、概述 ​

@oinone/cli（命令：oinone-frontend）是 Oinone 前端工程脚手架，用于快速生成基于 pnpm workspace 的 Oinone 前端工程。当前 CLI 版本：7.2.7，支持的 Oinone 框架版本：7.2.x（最新 7.2.9）/ 6.4.x（最新 6.4.12）。

功能特性：

  • 交互式创建工程，内置默认值与合理校验
  • 支持参数静默创建（适用于 CI/CD）
  • 企业版可选生成仓库凭证文件
  • 提供 cache 静态资源缓存管理
  • 提供 doctor 环境检查

二、环境要求 ​

阶段要求
运行 CLINode.js
安装生成的前端工程依赖建议使用 pnpm

注意

如果尚未安装 pnpm 及配套工具，可通过以下命令安装（推荐锁定版本，避免高版本带来的不确定性）：

bash
npm install -g pnpm@^9 lerna@9.0.3 rimraf@6.1.2

提示

在开始创建工程之前，请先完成附录2：前端环境配置中的全局配置（Node.js v22.13.0、pnpm@^9 等），避免后续安装依赖或启动项目时出现无法预知的异常。

三、安装 ​

bash
npm install -g @oinone/cli

验证安装：

bash
oinone-frontend --version

也可以使用 npx 直接运行，无需全局安装：

bash
npx @oinone/cli create my-project

四、创建项目 ​

（一）交互式创建 ​

直接运行 create 命令并跟随提示输入：

bash
oinone-frontend create

（二）静默式创建（推荐用于 CI/CD） ​

通过参数一次性传入所有配置，无需交互：

社区版：

bash
oinone-frontend create my-project \
  --oinone-version 7.2.0 \
  --edition community

企业版：

bash
oinone-frontend create my-project-enterprise \
  --oinone-version 7.2.0 \
  --edition enterprise

（三）使用 --company-name / --project-name 创建 ​

bash
oinone-frontend create \
  --company-name ss \
  --project-name oms \
  --oinone-version 7.2.0 \
  --edition community

注意

当同时使用 --company-name 和 --project-name 时，生成的工程目录名为 {company}-{project}-frontend（如上例为 ss-oms-frontend）。

（四）静态资源下载 ​

--download-static-resource 参数控制是否下载静态资源（如图标、图片等站点资源）：

bash
oinone-frontend create my-project \
  --oinone-version 7.2.0 \
  --edition community \
  --download-static-resource true

（五）演练模式（不落盘） ​

添加 --dry-run 参数可在不写入磁盘的情况下预检参数：

bash
oinone-frontend create my-project \
  --oinone-version 7.2.0 \
  --edition community \
  --dry-run

（六）创建 Oinone 6.4.* 工程 ​

bash
oinone-frontend create my-project-64 \
  --oinone-version 6.4.0 \
  --edition community

五、包命名与工程结构 ​

生成的前端工程为 pnpm workspace 管理的 monorepo 结构。模板中的包会根据 CLI 参数进行重命名：

模板包名生成后包名
ss-boot{company}-boot
ss-oinone{company}-oinone
ss-admin-widget{company}-admin-widget
ss-project{company}-project

注意

不仅包目录名会被替换，源代码中的 ss- 前缀和 @ss/ 作用域也会同步替换（如 @ss/ → @{company}/）。

生成工程目录结构：

shell
my-project/
├── pnpm-workspace.yaml       # pnpm workspace 配置
├── package.json               # 根 package.json
├── lerna.json                 # Lerna 配置
├── .npmrc                     # npm 镜像配置
├── eslint.config.ts           # ESLint 配置
└── packages/
    ├── ss-boot/               # 组装层（应用入口，Vue + Vite）
    │   └── src/
    │       └── main.ts        # 应用入口文件
    ├── ss-oinone/             # Oinone 集成层
    ├── ss-admin-widget/       # 无代码平台组件
    └── ss-project/            # 业务定制层

注意

以上为通过 oinone-frontend create my-project 生成的工程结构。若通过交互模式或 --company-name / --project-name 参数创建，工程目录名为 {company}-{project}-frontend（例如 ss-oms-frontend）。

六、启动项目 ​

生成工程后，依次执行以下命令安装依赖并启动开发服务器：

bash
cd my-project
pnpm install
pnpm run dev

提示

  • 在浏览器中打开终端输出的访问地址即可查看应用。
  • 国内网络环境下，项目内置的 .npmrc 已配置 npmmirror 镜像以加速依赖安装。

七、命令参考 ​

（一）全局参数 ​

参数说明
-l, --lang <lang>语言（zh-CN / en-US）
-v, --version输出版本号
-h, --help输出帮助

（二）oinone-frontend create [projectName] ​

参数说明
--company-name <name>静默模式：公司/组织简称
--project-name <name>静默模式：项目名；与 --company-name 同用时目录名为 {company}-{project}-frontend
--download-static-resource <boolean>是否下载静态资源（true / false）
-o, --oinone-version <version>Oinone 版本（7.2.0 / 6.4.0，仅支持次版本号）
-e, --edition <edition>版本类型：community / enterprise
-f, --force目标目录存在时覆盖/合并
-d, --dry-run演练模式：不落盘

（三）oinone-frontend doctor ​

参数说明
-o, --oinone-version <version>用于校验的 Oinone 版本（仅支持 6.4.* 与 7.2+）
bash
oinone-frontend doctor --oinone-version 7.2.0

（四）oinone-frontend cache ​

命令说明
cache info打印缓存目录信息（含已缓存文件及大小）
cache clean清理缓存的静态资源
bash
# 查看缓存信息
oinone-frontend cache info

# 清理静态资源缓存
oinone-frontend cache clean

提示

卸载 CLI 不会自动清理系统临时目录中的静态资源缓存。如需清理，请在卸载前执行 oinone-frontend cache clean。

八、版本与模板映射 ​

Oinone 版本模板目录说明
6.4.*template-6.4.0Oinone 6.4 前端工程
7.2+template-7.2.0Oinone 7.2 前端工程

版本发布日志：

警告

不支持的 Oinone 版本会直接报错，不会生成工程。

九、源码依赖（本地联调） ​

当需要对 Oinone 前端框架（oinone-kunlun）源码进行调试或二次开发时，可以通过以下方式将生成的业务工程与框架源码关联，实现本地联调。

（一）原理 ​

pnpm workspace 会将 packages/* 下的本地包通过符号链接映射到 node_modules。因此，将 oinone-kunlun 源码放入 packages/ 目录并注册其子包为 workspace 成员后，@oinone/kunlun-* 依赖即会解析到本地源码，对源码的修改即时生效。

（二）操作步骤 ​

1、克隆 oinone-kunlun 框架源码 ​

在生成工程的 packages/ 目录下克隆框架源码，并切换到对应分支：

bash
cd my-project/packages
git clone https://gitee.com/oinone/oinone-kunlun.git
cd oinone-kunlun
git checkout feat/7.2.0    # 7.2 模板对应此分支；6.4 模板请选择对应版本分支

2、修改 pnpm-workspace.yaml ​

编辑工程根目录的 pnpm-workspace.yaml，将 oinone-kunlun 的所有子包加入工作区：

yaml
packages:
  - 'packages/**'

3、检查 .npmrc 配置 ​

确保工程根目录的 .npmrc 中已配置以下参数，这是 pnpm 使用本地 workspace 依赖的关键：

link-workspace-packages=true
prefer-workspace-packages=true

4、安装依赖 ​

回到工程根目录，重新安装依赖以建立本地链接：

bash
cd ../..
pnpm install

5、处理 CSS 产物缺失 ​

oinone-kunlun 的 dependencies.ts 文件中引用了构建后才生成的 CSS 文件，在本地联调时这些文件尚不存在，会导致启动报错。直接注释掉对应的 CSS 导入语句即可：

需注释的文件一：packages/oinone-kunlun/packages/kunlun-vue/packages/dependencies/src/dependencies.ts

ts
// 本地开发时这些 CSS 产物尚未构建，先注释掉：
// import '@oinone/kunlun-vue-ui-common/dist/oinone-kunlun-vue-ui-common.css';
// import '@oinone/kunlun-vue-ui/dist/oinone-kunlun-vue-ui.css';
// import '@oinone/kunlun-vue-admin-layout/dist/oinone-kunlun-vue-admin-layout.css';
// import '@oinone/kunlun-vue-admin-base/dist/oinone-kunlun-vue-admin-base.css';
// import '@oinone/kunlun-vue-expression/dist/oinone-kunlun-vue-expression.css';

需注释的文件二：packages/oinone-kunlun/packages/kunlun-mobile-vue/packages/mobile-dependencies/src/dependencies.ts

ts
// 本地开发时这些 CSS 产物尚未构建，先注释掉：
// import '@oinone/kunlun-vue-ui-common/dist/oinone-kunlun-vue-ui-common.css';
// import '@oinone/kunlun-vue-mobile-base/dist/oinone-kunlun-vue-mobile-base.css';

提示

  • 若后续需要还原 CSS 导入，可通过 git checkout -- <file> 恢复文件。

6、启动开发服务器 ​

回到工程根目录启动：

bash
pnpm run dev

此时对 packages/oinone-kunlun/ 下任意源码的修改都会即时生效，可在浏览器中直接验证。

提示

  • 修改源码后如需还原，可用 git checkout -- <file> 恢复。
  • 若修改了 workspace 配置或新增/删除了依赖包，需重新执行 pnpm install 以更新链接。
  • 本地构建 oinone-kunlun 不仅耗时较长，且可能因环境差异产生不稳定因素。源码依赖仅推荐用于断点调试，项目构建请使用远程已构建好的 @oinone/kunlun-* 依赖包。