# @epxing/cli 中文文档

规范地址：https://npmcn.com/package/%40epxing/cli/

版本：0\.6\.0
npm 元数据更新时间：2026-11-13T08:04:05.669Z
中文译文更新时间：2026-11-13T20:00:17.733Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40epxing/cli
原文对照：https://npmcn.com/package/%40epxing/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-15T08:37:52.508Z
- 最新版本发布：2026-11-13T08:04:05.465Z
- 近 30 天下载量：3422（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

EPX 交互式工程开发、服务启动、构建、Vue3 迁移及技能安装工具

## 安装

```sh
npm install @epxing/cli
```

也可以使用：`pnpm add @epxing/cli`、`yarn add @epxing/cli`、`bun add @epxing/cli`

## README

# @epxing/cli

[完整公开 API、导入方式与示例](https://npmcn.com/package/%40epxing/cli/API.md)

独立的工程开发工具，包含交互菜单、开发服务、产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。创建和升级默认使用 `@epxing/*` 独立包，版本留空选择 npm 最新已发布版本（包含 beta），允许跨旧大版本；默认依赖始终使用 `major-N` 标签，标签未同步时报错而不回退固定版本。可用 `--packages-version` 指定版本或标签。创建成功和 `upgrade --apply` 后自动安装并刷新平台依赖与锁文件，`--no-install` 可跳过；预览不安装。CLI 使用自己的版本号；`@epxing/cli/vite` 提供产品构建插件，不依赖聚合包中的构建工具。

仓库旧 `pnpm epx create/migrate/upgrade` 默认转交独立 CLI，不再隐式注入 epx-frame；安装环境找不到独立 CLI 时明确提示安装，不回退旧聚合模式。只有显式 `--epx-frame` 保留聚合包。迁移阻塞返回失败状态，不安装旧包，需先处理迁移报告；实际页面和懒加载仍需构建及浏览器验收。

当前正式版本：`@epxing/cli@0.6.0`，CLI 使用 npm 公网 `latest` 标签，平台依赖默认使用对应 `major-N` 标签。CLI 与平台独立版本。完整流程见文档站“CLI 创建、升级与产品使用”；各包公开 API 随安装包的 `API.md` 提供。

`0.6.0` 将已验证的独立包迁移、动态大版本依赖、自动安装及浏览器验收技能作为正式版本发布。默认安装命令使用 latest；平台包仍可按原规则选择同一大版本的最新 beta，不与 CLI 的发布通道混淆。

`0.5.0-beta.18` 默认选择最新已发布平台版本（含 beta），依赖保持 major-N 标签，标签未同步时不退回固定版本。创建成功和升级应用后自动安装／刷新平台依赖及锁文件，预览只读，--no-install 可跳过安装。默认迁移到独立包，仍残留 epx-frame 时不误报完成；随包技能补充全量组件分组、浏览器实测及链接／截图验收要求。

`0.5.0-beta.17` 强化选择框宽度迁移 F20：AI 先核对本产品同类选择框范围与宽度来源，缺少有效宽度且无其它布局要求时，在产品专属容器内补 202px。AST 扫描增加宽度候选，保留已有 CSS、变量和明确的撑满布局；禁止全局覆盖 .el-select。扫描本身只读，不自动批量改业务源码。

`0.5.0-beta.16` 扩展随升级技能安装的 AST 扫描，检查 Element Button、Checkbox／Radio 和 Pagination 的高频弃用及旧协议；覆盖模板、JSX 和部分 h/createVNode 调用。技能要求执行扫描，动态配置继续追踪，扫描不自动修改业务源码；尚未接入 CLI migrate 自动调用链。

`0.5.0-beta.15` 创建与升级默认将平台依赖写为 `major-N`（如 `major-6`），跟随该大版本最新公开版本，包含 beta。已有独立包升级保持当前大版本；显式 `--packages-version` 仍可固定数字版本。lockfile 锁定实际安装版本，刷新依赖使用 `npm update`。八个平台包的发布流程维护各自的大版本标签。

`0.5.0-beta.14` 强化 F28 表单上下文透传检查：沿发送端、继承／包装组件、懒加载页签和原生根核对 form prop，补齐逐页签验收与宿主制品核对；保留 class/style、事件和上下文，不自动批量添加 prop 或关闭 attrs 继承。

`0.5.0-beta.13` 根据考核迁移报告补充插槽作用域、响应式状态、树刷新、异步依赖与移动布局复核。列表只读扫描新增同层插槽参数条件检测，覆盖解构、别名和局部变量遮蔽；模板解析失败非零退出，不自动改写业务条件。新增 F32–F34，明确历史报告对账和未定位问题的验收边界。

`0.5.0-beta.12` 合并考核升级经验，随技能交付跨产品复核清单及列表插槽、拖拽、图标三个只读扫描脚本。模型与样式按组件复核，覆盖模板、JSX/render、包装与继承链；扫描零命中不能替代未覆盖场景验收。CLI 更新不会覆盖已有产品技能，更新前须比较并保留自定义内容；新建目录可运行 epxing skill install 安装完整技能。

`0.5.0-beta.11` 将按需库的组件 CSS 放入对应 JS，模块加载完成前同步注入，共享样式去重；index.css 保留空文件兼容已登记 URL，整库兜底自带全部样式。可视化、设计器和预览组件写入预取排除清单，实际使用仍正常加载。新平台选择性预取普通组件；旧平台由新壳关闭后台预取。全量构建仍使用原有整体 CSS。Vite 深层动态导入仍引用的 CSS 文件继续保留并随组件按需加载。

`0.5.0-beta.10` 关闭产品库构建的 public 目录复制，避免旧 cmaps 和 index.html 混入 lib。创建模板、已有库配置迁移及 CLI 库构建保持一致；应用构建和源 public 文件保留。动态或展开的库配置仍报告人工核对。修复直接执行 npm 库构建时异步懒加载插件进入自身嵌套构建的问题。

`0.5.0-beta.9` 补齐已有标准库入口携带 `--full` 的迁移：升级后 `build:lib` 为 `node build-lib.mjs`，全量构建保留在 `build:lib:full`。预览不改文件，自定义构建命令和自定义入口文件继续保留并报告待接入。

`0.5.0-beta.8` 修复 Node 命令行扫描 HTML 实体时的 `document is not defined`：迁移、日期与主题扫描使用 Node 版 Vue 解析器，保留模板中的实体与原格式。旧版本遇到该问题时更新 CLI 后重新执行预览，不删除实体或添加假的 document。

`0.5.0-beta.7` 合并薪酬升级中的对象回显、必填校验和 ID 序列化注意事项，随技能交付参数路径修复脚本。创建与升级的标准工程默认懒加载，使用 `npm run build:lib --full` 或 `npm run build:lib:full` 全量构建。`epxing skill install` 安装该版本技能；已有技能默认受到保护，更新前先比较并保留产品自定义内容。保留主题及全局 CSS 变量逐组件验收与跨会话缺陷回归要求。

创建和升级会在可识别的独立包应用入口中预留默认注释的 `import { installLegacyFrame } from '@epxing/core'` 与 `installLegacyFrame(app)`。仅在需要加载依赖 `window.frame` 的旧远程库时手动取消两处注释，要求 core 5.3.0-beta.5 或以上版本；调用放在所需组件包安装后、远程库加载前。升级保留产品自定义代码及已经启用的调用，重复升级不重复添加提示。

平台包从 `5.3.0-beta.2` 起自动加载自身样式，产品无需手动引入各包的 `style.css`。创建和迁移使用此版本时，CLI 不再添加这些导入；指定旧版本时仍保留显式样式以兼容旧包。标签会先解析成具体版本再选择模板。已有显式导入可以保留，产品覆盖样式放在框架导入之后。

```powershell
npm install -g @epxing/cli --registry https://registry.npmjs.org/
epxing                             # ↑↓ + Enter 选择；Esc / Ctrl+C 取消
epxing dev --port 3000
epxing build --mode prd
epxing lib                         # 产品默认懒加载；平台目录构建完整聚合组件库
epxing lib --full                  # 产品完整打包
npm run build:lib                  # 新建或升级后的标准工程：默认懒加载
npm run build:lib --full          # 标准工程：显式全量（也可用 build:lib:full）
epxing lib --lazy                  # 显式选择懒加载，兼容已有命令
epxing create my-product
epxing migrate ./old-product
epxing migrate ./old-product --apply
epxing migrate ./old-product --transform-vue --to-vite --apply
# 指定固定版本时：epxing create my-product --packages-version 5.3.0-beta.2
epxing skill install --dir E:/products/my-product
```

从 0.4.0 起终端命令为 `epxing`，可与旧聚合 CLI 的 `epx` 共存。新产品直接依赖 `@epxing/core`、`@epxing/components`、`@epxing/utils` 等包。创建后进入目录安装依赖，再运行 `npm run dev`；默认端口 8080。工具安装阶段不会运行迁移或改产品文件。

新建产品的 `src/main.js` 使用 `createApp({ router: createFrameRouter() })`，安装 Components、Business 和产品插件，默认运行平台登录、菜单与系统首页。先在 `.env.development.local` 配置实际后端和应用参数。产品组件放入自动收集目录，`src/index.js` 仍是独立产品库入口，不包含本地应用启动代码。

从 `0.5.0-beta.4` 起，旧 CLI 生成的计数欢迎页在 main.js 与 App.vue 都保持原始模板时可由 upgrade 自动修复；自定义入口不覆盖。`epxing scan` 的 R4 提示尚未修复的原始欢迎页。升级技能区分 Vue2/webpack、Vue3 聚合包及已有独立包工程，报告补充平台启动验收。

组件校验 `epxing verify` 优先读取 lib 的清单或产物，无产物时按产品收集入口列源码候选，支持常规静态 glob 与 require.context；无法确定的动态规则要求先构建。源码候选不能代替产物及真实平台验收。

升级 CLI 后可用 `epxing skill install --dir <产品目录>` 安装新版升级技能。已有技能会受保护而退出；确认并保留产品自定义内容后，才使用 `--force` 替换。技能和命令随同一 CLI 版本交付。

`--epx-frame <版本或spec>` 仅用于显式选择旧聚合产品模式，与 `--packages-version` 互斥。普通命令与无参数交互引导均默认使用独立包，版本输入可直接回车。显式数字版本不查询网络；默认版本与标签需查询 npm，查询失败会退出，可通过固定版本离线生成。迁移遇到动态旧接口等无法确定的内容时返回 2，报告人工清单并保留原包模式；不会只切换一半导入。已有业务路由、store 和 install 注册代码保留；已有自定义 `PRODUCT-GUIDE.md` 会保留，另写 `EPXING-PACKAGES-GUIDE.md`。

```js
// vite.config.mjs：由创建模板自动配置；远程库构建启用共享映射。
import { frameDeps, epxShared, lazyLib } from '@epxing/cli/vite'
import epxIcons from '@epxing/icons'
// plugins: [frameDeps(), epxShared(), lazyLib({ root, enabled, glob, pkgName })]
```

开发和独立应用直接使用 npm 包。远程库构建通过宿主共享 core、组件、工具和 Vue；宿主需要同版本包并完成组件组安装。`epxing lib` 默认按需构建，`--full` 完整构建；按需部署必须上传整个 `lib/` 目录。`npm run build:app` 构建新模板的独立应用到 `dist/`。实体组件需要配置后端、元数据和权限。

使用 fnm/nvm 时，不同 Node 版本的全局包分别安装。切换到日常使用的 Node 版本后更新 CLI，再用 `epxing help` 确认开头为 `@epxing/cli`、`epxing --version` 确认版本。旧仓库的 `pnpm epx` 仍是该仓库自己的脚本。

## 命令

| 命令 | 行为 |
| --- | --- |
| `epxing` / `epxing menu` | 交互选择操作、工程目录、环境、端口和构建方式；管道支持数字输入 |
| `epxing dev` / `epxing serve` | 使用工程 `dev`、`serve` 或 `start` 脚本启动服务 |
| `epxing build` | 使用工程的构建脚本；只有 `build:lib` 的产品自动构建产品库 |
| `epxing lib` / `epxing build --lib` / `epxing lib --lazy` | 产品默认懒加载，优先 `build:lib:lazy`，否则使用 `build:lib` / `lib`；平台聚合库仍完整构建 |
| `epxing lib --full` / `epxing build --lib --full` | 产品完整打包，明确设置 `LAZY_LIB=false`；兼容旧 `--target lib` 脚本 |
| `epxing preview` | 使用 `preview` / `vite:preview`；没有脚本时使用工程本地 Vite |
| `epxing create` | 无参数进入创建引导，也可用参数直接创建 |
| `epxing migrate` / `epxing upgrade` | 无参数引导：目标版本、迁移范围、预览、确认应用 |
| `epxing skill install` | 安装技能，支持自定义目录和明确覆盖 |
| `epxing scan` / `epxing verify` | 迁移风险扫描 / 本地与线上组件清单校验 |
| `epxing theme [目录] [--apply]` | 补修产品/项目主题样式，默认只读预览；迁移时自动执行 |
| `epxing lint [--fix]` / `epxing circular` | 执行工程已有的代码检查、循环依赖检查脚本 |
| `epxing remote` / `epxing pkg <包名|all>` | 使用平台已有 `build:remote` / `build:pkg` / `build:pkgs` 脚本 |
| `epxing help` / `epxing --version` | 帮助 / 工具版本 |
| `epxing publish [选项]` | 递增当前包及 workspace 子包版本并发布 npm，默认正式版 patch |

### 发布当前工程的 npm 包

```sh
epxing publish --dry-run          # 只读查看范围和新版本，不构建或发布
epxing publish                    # 正式版 patch，发布到 latest
epxing publish --stable           # 显式选择正式版，与默认相同
epxing publish --beta             # beta；已有 beta.N 时递增 N
epxing publish --minor            # 中版本，例如 1.2.3 → 1.3.0
epxing publish --major            # 大版本，例如 1.2.3 → 2.0.0
epxing publish --beta --minor     # 下一中版本的 beta.0
epxing publish --version 2.3.0    # 显式指定所有目标包的新版本
epxing publish --no-root --dir .  # 只发布 workspace 子包，不包含根包
```

默认小版本指 patch（1.2.3 → 1.2.4）。从 beta 转正式版时去掉预发布后缀，例如 1.2.4-beta.2 → 1.2.4。当前包与子包统一版本号：基于目标包中最高的当前版本递增；显式 `--version` 则指定目标版本，新版本必须高于各包当前版本。workspace 中的独立 CLI 子包 `@epxing/cli` 不参与联动修改或发布；如进入 CLI 自身目录运行，则只发布 CLI 自己。

范围由当前工程的 package.json workspaces 或 pnpm-workspace.yaml 的 packages 列表决定，包含根包，跳过 private 包；支持普通路径、`*`、`**` 及 `!` 排除，不猜测未声明的子包。可用 `--dir` 指定工程、`--no-root` 排除根包。内部依赖更新到目标版本，workspace 简写保留在源码中，打包时转换成 npm 可安装的范围。

默认注册表为 npm 公网，可用 `--registry <地址>` 指定。命令保留项目原有 prepublishOnly/prepack 等脚本与发布守卫；本仓内部聚合包的公共发布仍要求显式设置 EPX\_PUBLISH\_PUBLIC=1，或用 `--no-root` 排除根包，不自动绕过守卫。先核对预览范围，再执行真实发布。

所有版本检查和 tarball 准备完成后，按依赖顺序发布；正式版使用 latest，beta 使用 beta，明确使用 public 访问级别。开始上传前失败会恢复原 package.json；上传开始后失败保留新版本和 `.cache/epxing-publish/<批次>/release.json`，记录已成功包，不自动重试或回滚远端。根据记录处理剩余包，避免整批重跑。成功后按项目包管理器刷新 lockfile，并提交版本变化；命令不自动修改 Git，不自动维护额外的 major-N 标签。首次发布或多包发布不是原子操作。

工程命令支持 `--dir <目录>`，默认从当前目录向上找到最近的 `package.json`；不会改为 CLI 全局安装目录。没有项目脚本时，dev/build/preview 可使用项目已安装的 Vite，不会自动下载构建工具。工程仍需先安装自身依赖。

产品懒加载构建需要 Vite 库配置（`build.lib`）、Vue 3 编译器和入口中的 `import.meta.glob('./产品目录/**/*.vue', { eager: true })`。CLI 使用产品本地 Vite 加载原配置；未接入按需插件时通过临时配置补入共享插件，不修改产品源码或原配置。已有按需插件保留其 eager 等自定义设置。构建后验证本次生成的 `index.manifest.json`、组件 chunks 和 `index.full.js`，缺少或沿用旧产物会报错，避免完整包被误判为懒加载成功。部署时上传整个输出目录（包含 CSS、chunks 和兜底包）。`--full` 会关闭按需插件；`--full` 与 `--lazy` 互斥。旧 webpack 产品先迁移到 Vite，或使用 `--full` 完整打包。自定义非 Vite 脚本须自行生成标准 `lib/` 按需产物。直接执行 `npm run build:lib` 仍由产品原脚本决定构建方式。

0.3.1 同时支持 `{ eager: true, import: 'default' }` 的直接组件入口写法。未显式设置 `assetsInlineLimit` 时，组件拆分保持 Vite 库模式的默认资源内联行为，避免图片改成平台根路径引用。

`--mode/-m`、`--port/-p` 支持旧的 `-mprd`、`-p3000` 写法。build 优先匹配 `build:<mode>`；`localize` 也匹配 `build:local`，其余情况向构建脚本传入 `--mode`。平台 `build:component` 包含多步构建，不追加 `--mode`，环境由工程脚本统一配置。

平台 `epxing build` 保留 `--thin`、`--no-designer`、`--no-dashboard`；产品工程不接受平台裁剪选项。需向工程脚本透传其他参数时使用 `--`，如 `epxing dev -- --host 0.0.0.0`。脚本原有的 pre/post 生命周期、自定义环境和多步构建会保留，失败退出码向上传递。

`create` 和 `migrate --apply` 自动写入 `runtime: "vue3"`。省略版本默认选择最新独立包；`--packages-version` 可固定版本，`--epx-frame` 显式选择旧聚合模式。迁移默认预览；apply 要求目标 Git 工作树干净。实际执行 `.vue` 转换时才按需安装并缓存 gogocode。标识表示迁移目标，仍需完成转换、构建和业务复测。

0.4.0 的迁移会同步适配平台主题：常见静态字号（12/14/16/20px）、圆角（2/4/8px，包括多角简写）和明确的语义颜色改为平台 CSS 变量，保留原值兜底。覆盖 Vue 样式块、template/JSX/render 内联样式和 src 中的 CSS/SCSS/Less；不改 scoped，不导入全局主题，不改圆形、胶囊、图标、打印及动画中的固定设计。动态样式、特殊字号/圆角、缩进式 Sass/Stylus 等列入复核清单，需按技能 E2 继续分析。返回码 2 表示有待复核项；不代表自动修复没有写入。已有 Vue3 工程可运行 `epxing theme <目录>` 预览，审查后加 `--apply`；无须重跑依赖迁移。最终产物须验证平台字号、圆角、明暗与密度切换、懒加载和样式隔离。

`epxing scan <目录>` 扫描静态风险，`epxing verify <目录> --online <地址|文件>` 对照组件清单。技能安装到 `.claude/skills/epxing-frontend-vue3-migrate/`，可用 `--skills-dir` 指定其他客户端要求的位置。已有技能默认不覆盖；确认替换使用 `--force`。平台基类源码分析仍需准备对应版本源码或文档。

在框架源码仓库发布工具，不需要构建平台 `lib/`：

```powershell
cd frontend/frame/packages/cli
npm login --registry https://registry.npmjs.org/
# 发布前调整为未发布过的新版本
# npm version <新的CLI版本> --no-git-tag-version
$previousPublicPublish = $env:EPX_PUBLISH_PUBLIC
try {
  $env:EPX_PUBLISH_PUBLIC = '1'
  npm publish --access public --registry https://registry.npmjs.org/
} finally {
  $env:EPX_PUBLISH_PUBLIC = $previousPublicPublish
}
```

发布账号需要拥有 `@epxing` 名称空间的发布权限，并完成 npm 要求的发布身份验证。`publishConfig` 固定公开发布到 npm 公网；上面的命令仅为这次操作启用共享守卫的显式公开发布开关，并在结束后恢复原值。`prepack` 自动构建工具并带入当前技能文件。可在框架根执行 `pnpm build:cli`，或在这里运行 `npm pack` 生成可独立安装的 tgz。技能与 CLI 同版本交付，平台升级不要求工具同步发版；工具规则、模板或技能更新时才发布新 CLI。新平台若改变接口或构建约定，仍需验证并更新相应工具规则。

在框架根运行 `npm --prefix packages/cli test`，验证真实 tgz 的离线安装、无平台依赖运行、创建、迁移、扫描和技能安装。

首次发布前，需创建或加入 npm 的 `epxing` 组织。可用 `npm org ls epxing --json --registry https://registry.npmjs.org/` 核对组织角色。若发布返回 `403 Two-factor authentication or granular access token with bypass 2fa enabled is required`，表示当前发布凭据未满足 npm 要求；仅 `npm whoami` 成功不代表可以发布。可在 npm 网站创建具有目标 scope 发布权限、启用 `Bypass 2FA` 的细粒度令牌，并配置到本机用户 npm 设置；令牌不写入项目或发布包。参见 [npm 发布身份验证要求](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)。

令牌的 `Packages and scopes` 权限应选择 `Read and write (publish and stage)`，范围覆盖 `@epxing`；`Read and write (stage only)` 无法直接发布。`Organizations` 里的读写权限只管理组织、团队和成员，不授予组织包的发布权限。首次创建包时需覆盖相应 scope。参见 [npm 令牌权限说明](https://docs.npmjs.com/creating-and-viewing-access-tokens/)。

## 常见问题

### @epxing/cli 是什么？

EPX 交互式工程开发、服务启动、构建、Vue3 迁移及技能安装工具

### 如何安装 @epxing/cli？

在项目目录运行 npm install @epxing/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 epxing，可以用 npx epxing 直接运行。

### @epxing/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @epxing/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @epxing/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @epxing/cli 可以商用吗？

@epxing/cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @epxing/cli 的下载量有多少？

根据 npm 官方下载统计，@epxing/cli 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,422 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @epxing/cli 还在维护吗？

最新版本 0\.6\.0 发布于 2026/11/13（今天）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。