BBC 8.0 前端开发环境搭建
本文用于在本机启动 BBC 8.0 PC UI workspace，包括买家 PC 端、商家管理端和平台管理端。移动端是独立工程，不在本流程中安装或启动。
1. 准备环境
请先安装以下工具：
| 工具 | 要求 |
|---|---|
| Git | 用于获取 8.0 源码和确认分支 |
| Node.js | pnpm@11.7.0 至少要求 22.13；本阶段已验证 22.17.0 |
| Corepack | 随受支持的 Node.js 提供，用于启用项目约束的 pnpm |
| pnpm | 项目根目录固定为 pnpm@11.7.0 |
启用并检查包管理器：
node -v
corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm -v
pnpm -v 应输出 11.7.0。项目安装前置检查会拒绝 npm 或 Yarn，不要为绕过安装问题改用其它包管理器，也不要删除 pnpm-lock.yaml。
Node 版本基线
当前项目根 package.json 尚未声明 engines.node，但 pnpm@11.7.0 至少要求 Node.js 22.13。本阶段使用 Node.js 22.17.0 完成了干净安装和三端 build:dev；团队的 CI 和开发机应固定同一已验证版本。
2. 获取 BBC 8.0 源码
从项目交付渠道或团队代码仓库取得 BBC 8.0 PC UI 源码。不要使用只包含 7.x 的旧公开分支代替 8.0，也不要从相邻目录猜测目标仓库。
公开源码边界
截至 2026-08-20，公开 Gitee 的 bbc-se/pc-ui 和 bbc-se/mobile-ui 尚未提供 8.0 分支。需要联系项目授权交付方取得实际 BBC 8.0 PC UI 仓库地址或源码包；不能把公开的 7.4.0 分支当作 8.0。公开 8.0 源码发布前，本节只适用于已经取得授权交付物的使用者。
使用 Git 交付时，可按实际仓库地址执行：
git clone --branch 8.0 <BBC 8.0 PC UI 源码仓库地址> pc-ui
cd pc-ui
git branch --show-current
最后一条命令应输出 8.0。如果拿到的是源码压缩包，解压后也应先确认根目录至少包含：
apps/
packages/
config/
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
8.0 PC UI 是单一 workspace，不需要分别进入三个应用安装依赖。三个应用的对应关系如下：
| 目录 | 应用 |
|---|---|
apps/pc | 买家 PC 端 |
apps/seller | 商家管理端 |
apps/admin | 平台管理端 |
3. 安装依赖
在项目根目录执行：
pnpm install --frozen-lockfile
--frozen-lockfile 会在依赖声明与锁文件不一致时明确失败，避免本机静默改写锁文件。需要升级依赖时，应作为独立开发任务处理，而不是在环境搭建过程中临时修改版本。
4. 配置本机环境
仓库提供 .env.development 作为开发环境配置。需要覆盖 API 或域名时，复制为只在本机生效的文件：
cp .env.development .env.development.local
.env.development.local 已被 Git 忽略。只修改这个本机文件，不要为了个人联调地址直接改动并提交公共 .env.development。
常用配置项：
| 变量 | 说明 |
|---|---|
VITE_API_GATEWAY | 统一 API 网关；留空时使用下面四类 API 地址 |
VITE_API_BASE | 基础 API 地址 |
VITE_API_BUYER | 买家业务 API 地址 |
VITE_API_SELLER | 商家业务 API 地址 |
VITE_API_ADMIN | 平台管理 API 地址 |
VITE_DOMAIN_PC | 买家 PC 端地址 |
VITE_DOMAIN_MOBILE | 外部移动端地址，用于跨端链接；不会启动移动端应用 |
VITE_DOMAIN_SELLER | 商家管理端地址 |
VITE_DOMAIN_ADMIN | 平台管理端地址 |
本地示例：
VITE_API_GATEWAY=http://localhost:8080
VITE_DOMAIN_PC=http://localhost:3000
VITE_DOMAIN_MOBILE=http://localhost:3001
VITE_DOMAIN_SELLER=http://localhost:3002
VITE_DOMAIN_ADMIN=http://localhost:3003
如果后端不是统一网关，请分别填写 VITE_API_BASE、VITE_API_BUYER、VITE_API_SELLER 和 VITE_API_ADMIN。API 必须允许当前浏览器来源访问，否则会出现 CORS 错误。
不要在 VITE_* 中保存秘密
所有 VITE_* 变量都会进入浏览器代码。不要写入数据库密码、服务端私钥、长期令牌或其它不能公开给浏览器的信息。
完整配置优先级、部署路径、CDN 和功能开关见配置文件。
5. 启动应用
按需要启动单个应用：
pnpm dev:pc
pnpm dev:seller
pnpm dev:admin
也可以同时启动三个应用：
pnpm dev
默认访问地址：
| 应用 | 地址 |
|---|---|
| 买家 PC 端 | http://localhost:3000 |
| 商家管理端 | http://localhost:3002 |
| 平台管理端 | http://localhost:3003 |
这些端口来自三个应用各自的 vite.config.ts。3001 只是默认移动端域名占位，不属于当前 workspace 的开发服务器；8.0 也没有独立的 3004 装修端。
修改 .env.development.local 后必须重启对应 Vite 开发服务。
6. 完成基线检查
首次安装完成后，建议在根目录执行：
pnpm typecheck
pnpm lint
pnpm locale:check
pnpm build:dev
如果只开发单个应用，可以先执行对应构建：
pnpm build:dev:pc
pnpm build:dev:seller
pnpm build:dev:admin
单端构建只覆盖目标应用。修改 packages/*、config/*、根构建配置或多个应用时，应执行完整的 pnpm build:dev。
构建通过只说明静态产物可以生成，不代表登录、动态菜单、接口权限或业务流程已经验收完成。