Work 前端项目安装指南¶

📄 创建: 刘泽伟 2026-08-03 · 修改: 刘泽伟_w 2026-08-20

https://doc.xpku.com/raw/tech/frontend/bams-work.md

0. 开发前准备¶

环境要求：Node.js >= 22.14.0，Yarn 1.22.x
建议提前准备：可访问公司 Git 仓库的账号权限

如果本机尚未安装 Yarn（或版本不符合 1.22.x），可按以下示例安装（任选其一）：

# 使用 npm 全局安装 Yarn 1.x
npm i -g yarn@1.22.22

node -v
yarn -v

1. 一键安装脚本（可选）¶

说明：适用于首次搭建环境的快速安装；如遇到网络/权限/公司 Git 访问问题，可按「2. 本地手动安装（必须）」中的步骤手动安装排查。

执行提示：脚本会在执行过程中输出交互式操作指引，执行后请按照终端提示继续完成安装/依赖下载等步骤。

安全提示：建议先下载脚本并查看内容，再执行安装。

curl -fsSL https://doc.xpku.com/mcp/files/install-bams-work.sh -o install-bams-work.sh
sh install-bams-work.sh

1.1 macOS / Linux¶

curl -fsSL https://doc.xpku.com/mcp/files/install-bams-work.sh | sh

1.2 Windows¶

Windows 建议在以下任一环境中执行同一条命令：

WSL（Ubuntu 等 Linux 子系统）
Git Bash（随 Git for Windows 安装）

curl -fsSL https://doc.xpku.com/mcp/files/install-bams-work.sh | sh

2. 本地手动安装（必须）¶

2.1 安装 bams-work（主仓库）¶

cd ~
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/bams-work.git
cd bams-work
git checkout dev

2.2 安装通用/业务组件仓库（按需）¶

说明：bams-work 使用 Yarn Workspaces 管理多个子仓库，业务开发通常需要把相关组件仓库 clone 到 bams-work 根目录下。

cd ~/bams-work

# 通用组件库（常用）
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/bams-components.git

# 业务组件仓库（只 clone 你要开发/调试的）
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/energy-ui.git
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/device-ui.git
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/mes-touch-ui.git
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/pds-ui.git
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/admin-ui.git

# 其他业务组件仓库（示例：把仓库名替换成你实际要调试的）
git clone https://git.cnbmtech.com/CNBM-CIMS/customized-project/BXJC/front-end/<your-business-ui>.git

2.3 切分支 + 安装依赖（一次完成）¶

cd ~/bams-work

# 各仓库切到 dev 分支（只对已 clone 的仓库执行）
cd bams-components && git checkout dev
cd ../energy-ui && git checkout dev
cd ../device-ui && git checkout dev
cd ../mes-touch-ui && git checkout dev
cd ../pds-ui && git checkout dev
cd ../admin-ui && git checkout dev

# 回到根目录统一安装（链接 workspaces）
cd ~/bams-work
yarn install

3. 环境变量和开发代理配置¶

3.1 环境变量配置说明：¶

环境变量文件统一放在 .envs/ 目录，可使用脚本创建：

cd ~/bams-work
yarn create-env

目前仓库内已提供的环境文件（如已存在对应文件，可直接使用，无需重复创建）：

.envs/.env.dev-bxjc：bxjc 环境
.envs/.env.dev-bams：bams 环境
.envs/.env.dev-qls：qls 环境
.envs/.env.dev-mock：mock 环境
.envs/.env.dev-apex：apex 环境
.envs/.env.dev-pdc：pdc 环境
.envs/.env.production：production 环境（构建/发布用）

关键约束：

PORT 必须与 PROXY_TARGET 的端口保持一致（以 PROXY_TARGET 端口为准），否则本地代理会异常

更详细说明见：.envs/README.md

3.2 开发代理配置说明：¶

开发代理由根目录 vue.config.dev.js 提供（该文件在 .gitignore 中，不会提交），首次拉仓需按模板生成：

cd ~/bams-work
cp vue.config.dev_template.js vue.config.dev.js

vue.config.dev_template.js 内的 proxy.target 默认读取环境变量 PROXY_TARGET，因此通常只需要在 .envs/.env.* 中配置：

PORT=8090
PROXY_TARGET=http://192.168.7.11:8090

代理路由（示例）：
静态资源：/bams-assets
UMD/组件加载：/bams-ui-umd
bams-work 接口：/bams-app、/preview、/admin-api（不建议随意改动）
业务接口：/mes-api、/pds-api 等（可按业务需要在 vue.config.dev.js 中补充或单独指定 target）
修改 vue.config.dev.js 或环境文件后需要重启开发服务才会生效

4. 创建组件（脚手架）¶

说明：以下用 energy-ui 作为示例，实际请替换为你真实开发的业务仓库目录名。

4.1 创建基础组件包（base-*)¶

用于放通用能力（apis、utils、store、components 等）。

cd ~/bams-work
yarn create-ui-base --dir energy-ui --name base-apis
yarn install

4.2 创建业务组件包（ui-*)¶

用于放具体业务能力组件（可依赖 base-*）。

cd ~/bams-work
yarn create-ui-component --dir energy-ui --name ui-order-list
yarn install

4.3 创建页面组件包（page-*)¶

用于菜单编码对应页面组件：只负责布局/组装，可引用多个 ui-* 业务组件，不建议在页面组件中写业务逻辑。

cd ~/bams-work
yarn create-ui-page --dir energy-ui --name page-order-list
yarn install

5. 开发组件（使用文档）¶

5.1 启动 UI 组件开发服务¶

根据目标环境选择启动命令（支持 bxjc、bams、qls、mock 等）：

cd ~/bams-work
yarn dev:ui bxjc ui-order-list

5.2 启动页面组件（带菜单布局）¶

cd ~/bams-work
yarn dev:ui bxjc page-order-list -l pc
yarn dev:ui bxjc page-order-list -l touch

5.3 预览地址与路由规则¶

默认预览：http://localhost:8080
带菜单布局的页面预览示例：http://localhost:8080/bxjc-cmp/work/pageOrderList

路径拆解：

bxjc-cmp：应用 id（决定拉取哪套菜单数据）
work：固定路径，不可修改
pageOrderList：组件编码（组件包名的驼峰形式，由 page-order-list 转换而来；系统菜单配置使用该编码）

常见应用 id：

bxjc-mes：生产、质量
bxjc-cmp：一体机
bjjc-energy：能源管理
bxjc-device：设备管理
bams-pds：调度管理

6. 构建与上线发布¶

说明：本项目上线部署建议使用 project-startr 打包应用的方式（而非直接说明 UMD 产物）。发布前必须先生成入口文件，否则页面组件不会被正确打包进应用。

6.1 打包业务中台 bams-app（可选）¶

写入生产环境变量（必须），生产环境变量是由部署平台在上线时外部注入；构建时默认使用 production，请在构建前把生产变量写入到 .envs/.env.production 中，请参考现有的 .envs/.env.production 配置项按需填写。

bams-app 代表业务中台，强制依赖 apex-web 组件包仓库。

cd ~/bams-work
git clone https://git.cnbmtech.com/CNBM-CIMS/products/bams-apex/apex-web.git
cd apex-web
git checkout dev
cd ~/bams-work
yarn install

打包 bams-app 产物：

cd ~/bams-work
yarn create-pages-entry --dir apex-web --type page
yarn build:bams-app

打包产物目录：dist/

6.2 打包业务应用（project-startr）¶

写入生产环境变量（必须），生产环境变量是由部署平台在上线时外部注入；构建时默认使用 production，请在构建前把生产变量写入到 .envs/.env.production 中，请参考现有的 .envs/.env.production 配置项按需填写。

打包 bams-app 产物：

cd ~/bams-work
yarn create-pages-entry --dir energy-ui --type page
yarn build:project-startr

打包产物目录：dist/

6.3 部署上线要点（简版）¶

将 dist/ 产物发布到静态资源服务器/容器镜像（按项目的 Nginx / 网关 / K8s 规范）
系统菜单配置的组件编码填写为组件包名的驼峰形式（例如：page-order-list -> pageOrderList）
浏览器如遇到缓存问题，优先清缓存或调整静态资源缓存策略

注意：一般情况下 bams-app 和 project-startr 不会部署在同一个容器内，请走不同环境变量配置进行容器部署。

7. 组件复用示例¶

业务中的公共组件，建议在对应业务仓库内创建通用组件包供复用：

cd ~/bams-work
yarn create-ui-component --dir energy-ui --name ui-echarts --desc 能源管理通用组件
yarn install

引用示例：

import { UIEcharts } from "@energy-ui/ui-echarts";

更多细节请参考：

bams-work/README.md
.envs/README.md