@infly/libs

介绍

@infly/libs 是不受 Vue、React 等前端框架限制的独立 JavaScript 工具库。包根入口无副作用；HTTP、Token、文件处理、Docker/Compose、通用项目命令等能力可被不同技术栈使用。

Vue 2 专属的 Permission、Vuex store、实例 mixin、Vue CLI 预览和 webpack 配置集中在 adapters/vue2/，避免核心入口依赖 Vue 项目约定。

注意事项

新代码应显式导入 Vue 2 适配路径。Webpack 适配器仅服务脱离 admin-monorepo 的子模块独立构建；Monorepo 根构建不会调用该实现。

软件架构

@infly/libs
├── index.js                    # 框架无关、无副作用的包根入口
├── module/                     # HTTP、Token、格式化等通用模块
├── tools/                      # 文件与项目命令等通用工具
├── build/
│   ├── docker/                 # Docker/Compose 工具
│   └── build-dist/             # 构建产物处理
├── adapters/vue2/
│   ├── module/file-export.js  # 注入请求与 Element UI 能力的 Vue2 导出 mixin
│   ├── module/Permission.js    # Vue Router/Vuex 权限适配
│   ├── store/                  # Vuex 模块
│   ├── project-preview.js      # Vue CLI 预览
│   ├── script-config.js        # Vue CLI 脚本模板
│   ├── vite/                   # Monorepo Vite 定位与兼容入口
│   ├── webpack5/               # 独立子仓 Webpack 兼容适配器
│   └── postinstall.js          # 仅 Vue 2 项目执行初始化
├── bin/cli.js                  # 命令行入口
└── dataInit/                   # 公共枚举

Vue2 文件导出适配：

import { fileExportMixin } from "@infly/libs/adapters/vue2/module/file-export.js";

Vue.mixin(fileExportMixin);

适配器只负责从 Vue 实例注入 $axios、$message、$msgbox 和 $loading；确认、请求与下载流程由 @infly/ts-libs 的 exportFile 实现。@infly/ui 不公开该 mixin。

根入口加载示例：

const inflyLibs = require('@infly/libs');

根入口继续保留历史 init() API，但只在显式调用时懒加载 Vue 2 适配器，不会在 require('@infly/libs') 时自动执行：

inflyLibs.init();

安装教程

# 项目安装
npm/pnpm install @infly/libs

Docker 镜像构建

在应用目录中执行：

infly-libs build:docker --local --env prod

可通过可选参数 --cicd-url 在构建和镜像推送全部成功后输出蓝色发布系统链接。支持等号和空格两种传参形式：

infly-libs build:docker --local --cicd-url="https://deploy.example.com/projects/admin/"

infly-libs build:docker --local --cicd-url "https://deploy.example.com/projects/admin/"

未传 --cicd-url 时保持原有输出。参数值必须是合法的 HTTP/HTTPS URL，且不能包含用户名、密码或控制字符。

需要在推送前验证镜像自身的 Docker HEALTHCHECK 时，可启用可选健康门禁：

infly-libs build:docker --local --health-check --health-timeout=60

• --health-check：构建后启动临时容器，只有镜像状态变为 healthy 才推送；失败或超时会清理临时容器并阻止所有标签推送。
• --health-timeout：等待秒数，范围为 1 到 600，默认 60。
• --health-add-host：可选的临时容器主机映射，格式为 HOST:IP 或 HOST:host-gateway，用于镜像启动时必须解析内部服务名的场景。

未启用 --health-check 时保持原有“构建后直接推送”行为。镜像必须在 Dockerfile 中定义 HEALTHCHECK，否则门禁失败。

发布不可变 commit 镜像时还可组合：

• --standalone：即使当前项目位于 submodule，也强制以当前 Git 仓库根目录和本地 Dockerfile 为构建上下文；命令必须在该仓库根目录执行。
• --commit-only：只构建并推送 commit 标签，不更新环境标签或 latest。
• --tag-prefix <prefix>：为本次调用产生的全部镜像标签添加统一前缀（如隔离标签 qc-）。前缀必须以字母或数字开头，最多 40 字符，只允许字母、数字、点、下划线和连字符。设置前缀后本地不产生裸发布标签，发布标签应由 CI 在质量门禁通过后晋升产生。

可复用的本地质量发布

需要在多个前端复用“项目检查 → 可选 SonarQube → 构建/健康门禁/推送”时，在应用 package.json 声明项目差异：

{
  "infly": {
    "dockerRelease": {
      "checks": ["lint", "typecheck", "test:coverage"],
      "coverageReport": "coverage/lcov.info",
      "sonar": true
    }
  }
}

然后执行：

infly-libs release:docker --local --health-check --health-timeout=60

checks 中的名称必须对应应用已有的 pnpm script；任一检查、覆盖率文件验证、Sonar Quality Gate 或镜像健康门禁失败，命令都会退出且不会推送镜像。sonar 默认为 true；设为 false 时由 CI 单独负责扫描和 Quality Gate。本地启用 Sonar 时必须通过当前进程环境或应用根目录下被 Git 忽略的 .env.production.local 提供 SONAR_TOKEN，并确保 sonar-scanner CLI 可执行；当前进程环境变量的优先级更高。release:docker 会拒绝含未提交文件的应用工作树，固定使用 12 位应用 commit 作为镜像标签，并把完整 commit 写入 OCI revision label；普通 build:docker 的原有版本来源保持不变。应用差异保留在应用配置，通用编排由 infly-libs 维护。

受控紧急构建可使用 --emergency 跳过 checks、覆盖率文件校验和 Sonar，但必须提供 8～200 个字符且无控制字符的 --emergency-reason，并同时启用 --standalone --commit-only --health-check。紧急模式仍执行工作树干净检查、commit/revision 解析、镜像构建、健康检查和推送；缺少任一保护参数会在调用 Docker 前失败。

HTTP 环境保护配置

module/REST.js 不内置任何项目域名。应用如需在测试环境误连正式接口时告警，应由应用显式注入完整的正式 API 基地址：

const service = createService({
  productionBaseURLs: ["https://api.example.com"]
});

未传 productionBaseURLs 时不启用该项目级域名判断。

配置驱动的项目命令

project 命令将多平台项目的开发和构建目标从 package scripts 移到项目配置：

infly-libs project
infly-libs project dev
infly-libs project build

命令从当前目录 package.json 的 infly.targets、infly.dev 和 infly.build 读取配置。交互选择会追加“退出”选项；选择退出或按取消键时会正常结束，不执行后续命令。项目命令不支持 --config 文件入口。

未指定 action、target 或构建环境时，会在 TTY 中显示单选菜单。CI/CD 必须显式传参：

infly-libs project dev --target QDXY
infly-libs project build --env stage --target SQ223

--dry-run 只打印带 VUE_APP_PLATFORM 的命令计划。infly.targets 推荐使用平台代码数组，例如 ["DEFAULT", "MER", "JXEE"]；同时兼容对象形式，对象值中的 label 只用于交互显示。普通 target 就是注入 VUE_APP_PLATFORM 的平台代码，批量构建通过 build.presets 组合多个 target。

dev.command 以及 build.before/command/after 同时支持字符串和参数数组。字符串按空白拆分为可执行文件和参数，不经过 shell；参数本身包含空格时应继续使用数组形式。

build.environments 推荐使用 选择键:实际 mode 数组，例如 ["prod:production", "stage:staging"]；CLI 使用冒号前的值进行选择，并把冒号后的值作为 --mode 参数。没有冒号时选择键和 mode 同名。对象形式继续兼容，用于自定义 label、mode 或 args。项目如果自行管理构建入口，应设置 infly.buildConfigs.manageScripts=false，避免安装阶段重新写入传统 build:prod/build:stage。

Docker Compose 版本发布

docker:compose 面向已有 Compose 文件的镜像版本递增、配置校验和构建，与上面的 Dockerfile/commit-tag build:docker 流程互不替代：

infly-libs docker:compose --target yhqy --bump patch

默认从当前目录 package.json 的 infly.docker.targets 读取目标，并以该 package 所在目录解析 Compose 相对路径；省略 --target 时在 TTY 中交互选择。--config 外部 JS 配置和原有 --project-dir + --file 直传方式继续兼容。

参数约束：

• --target：选择 infly.docker.targets 或外部配置中的目标；非交互环境必须显式传入。
• --config：可选的外部 JS 配置文件，使用 targets.<name>.file 结构。
• --project-dir + --file：不使用 target 配置时的兼容直传方式，Compose 文件不能越出 project-dir。
• --bump patch：目前只支持 patch 递增，且 Compose 中必须恰好有一个 x.y.z 镜像 tag。
• --push：显式推送；未传时只执行 docker compose config 和 build。
• --dry-run：只打印版本变化和计划命令，不写文件、不调用 Docker。

构建、校验或推送失败时，命令会恢复原 Compose 内容。公共包不内置 yhqy、qdxy 等业务目标映射；目标配置和单一发布 script 应归 Compose 所在项目所有。