BBC 8.0 前端常见问题
为什么不能使用 npm 或 Yarn 安装？
项目根 package.json 通过 packageManager 固定使用 pnpm@11.7.0，安装前置脚本也会拒绝其它包管理器。先在项目根目录执行：
corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm -v
pnpm install --frozen-lockfile
不要通过删除 pnpm-lock.yaml、改用 npm/Yarn 或跳过前置检查来掩盖依赖问题。这些操作会破坏多应用 workspace 的可复现安装。
为什么旧文档中的 Node.js 14 不能继续使用？
8.0 已升级到 TypeScript、ESLint、Vite 和 pnpm 的新版本，Node.js 14 不再是合适的开发基线。本指南推荐 Node.js 22，并要求本机与 CI 使用一致版本。
如果安装或构建仍报 Node engine 错误，先记录 node -v、pnpm -v 和完整错误，再按团队确认的支持版本调整；不要只针对单个依赖强行降级。
仓库里没有单独的本机环境模板，配置从哪里创建？
当前 8.0 源码仓库跟踪 .env.development、.env.test 和 .env.production。本机开发覆盖文件应从开发环境文件创建：
cp .env.development .env.development.local
.env.development.local 已被 Git 忽略。修改后重启对应 Vite 服务。不要把个人联调地址直接提交到公共环境文件。
启动后请求到了错误的 API 地址
开发模式的有效配置按以下顺序解析：
- CI、Jenkins 或当前进程注入的环境变量。
.env.development.local中的本机覆盖值。.env.development中的团队开发环境值。config/api.ts中的代码兜底值。
Vite 构建配置会让当前进程的 process.env 覆盖 loadEnv() 读取的文件值，因此排查 CI 构建时应先确认流水线实际注入了哪些变量，但不要在日志中回显敏感配置。
如果设置了 VITE_API_GATEWAY，未单独覆盖的 Base、Buyer、Seller、Admin API 都会使用该网关；否则分别检查 VITE_API_BASE、VITE_API_BUYER、VITE_API_SELLER 和 VITE_API_ADMIN。
修改后必须重启 Vite。仍有问题时，在浏览器 Network 面板确认最终请求地址，并检查是否由代理、浏览器缓存或错误的构建产物导致。
API 可以访问，但浏览器仍提示 CORS 或 Mixed Content
这是浏览器与部署边界问题，不应通过页面代码吞掉错误：
- CORS：后端或网关必须允许实际前端 Origin、请求方法和 Authorization 等请求头。
- Mixed Content：HTTPS 页面不能请求 HTTP API、图片、WebSocket 或上传地址。
- 上传失败：同时检查网关请求体大小、超时和对象存储跨域策略。
修复后应重新验证登录、刷新 token、上传和实时消息，而不只是验证一个公开 GET 接口。
修改环境变量后为什么页面没有变化？
Vite 在开发服务启动或构建时读取 .env.*。修改后需要：
- 开发环境：停止并重新启动
pnpm dev:<端>。 - 测试环境：重新执行
pnpm build:test或目标端命令。 - 生产环境：重新执行
pnpm build并重新发布对应dist。
只修改服务器上的 .env.production，不会改变已经构建好的静态文件。
三个开发端口分别是什么？
| 应用 | 默认端口 |
|---|---|
| 买家 PC 端 | 3000 |
| 商家管理端 | 3002 |
| 平台管理端 | 3003 |
3001 是跨端链接配置中的默认移动端地址，不会由当前 workspace 启动。8.0 没有独立的 3004 装修应用，装修编辑器由平台端或商家端按需加载。
页面刷新或直接打开二级 URL 为什么返回 404？
三个应用使用 Vue Router history 模式。正式部署时 Web 服务器必须将不存在的前端路由回退到对应应用的 index.html。
独立域名部署通常需要：
location / {
try_files $uri $uri/ /index.html;
}
子路径部署还必须保证 VITE_BASE_*、Vue Router base、Nginx location 和静态目录完全一致。不要只测试首页；还要复制二级 URL 到新标签页并直接打开。
构建后静态资源 404
按顺序检查：
- 当前端的
VITE_BASE_*是否与部署路径一致。 VITE_ASSETS_*是否指向本次构建对应的 CDN 前缀。- CDN 是否完整上传了本次
dist的资源。 - Nginx
root或alias是否指向正确应用的产物。 - HTML 和资源是否混用了不同版本的发布包。
资源问题修复后清理浏览器/CDN 缓存并重新检查所有 JS、CSS、字体和图片请求，不能仅凭首页可见就判断部署成功。
平台端或商家端新增菜单后为什么不显示？
后台菜单不是由前端静态路由树单独决定的。一个可点击菜单页面至少需要：
- 在对应端
router/page-routes.ts注册页面。 - 在
router/route-components.ts绑定 Vue 组件。 - 后端 current 菜单接口返回与 route name 相同的 identifier。
- 当前角色拥有该菜单权限。
- 对应功能开关没有过滤该页面。
菜单父子层级、同级顺序、可见标题和非空图标以后端接口为准。纯父分组只需在后端维护，不要在前端创建功能不明的占位页面。
菜单能看到，但点击后空白或跳转失败
常见原因是 page-routes.ts 中的 name 没有在 route-components.ts 中绑定，动态 import 路径错误，或者后端 identifier 与本地 name 大小写不一致。
检查浏览器控制台中的权限诊断和动态 import 错误。不要用一个空白兼容页静默接住未知 identifier，这会隐藏真实配置问题。
隐藏详情页为什么被权限守卫拦截？
后台详情、编辑和审核页通常设置 hidden: true，并通过 backName 或 backNames 继承入口页面权限。缺少返回关系的隐藏页不会被自动放行。
同时确认页面已在 route-components.ts 绑定。需要保留入口筛选和分页时，使用 withReturnTo() 构建目标地址，并由 usePageBack() 统一返回。
关闭 IM、直播或分销后仍出现入口
先检查对应环境文件中的功能开关：
VITE_IM=false
VITE_LIVEVIDEO=false
VITE_DISTRIBUTION=false
开关在启动或构建时读取，修改后必须重启或重建。后台权限路由会过滤相应候选页面；页面内部的自定义按钮也必须使用统一功能开关判断，不能只隐藏菜单。
多语言 key 缺失
语言资源位于 packages/locales。修改后执行：
pnpm locale:check
后台可见菜单标题优先由后端菜单接口提供，页面自身标题和旧路由兼容映射仍可能需要语言 key。新增文案时同时检查所有受支持语言，不要只补当前页面看到的一种语言。
pnpm typecheck 报共享包错误，能只在页面绕过吗？
不能。packages/api、packages/config、packages/core、packages/components 和 packages/utils 会影响多个应用。共享类型错误应在事实源修复，而不是在单个页面增加 any、忽略指令或重复类型。
可以先缩小 API 类型问题：
pnpm typecheck:api:strict
最终仍应执行完整 pnpm typecheck 和受影响的 pnpm build:dev。
packages/api/models 可以添加接口函数吗？
不可以。该目录保存从后端 Java VO/DTO/DO 生成的 TypeScript 类型，根入口使用 type-only 导出。把运行时函数写入生成文件会导致生成覆盖业务逻辑，也无法从包根获得运行时导出。
- 单端业务接口：放在对应的
apps/*/src/api。 - 跨端运行时接口：建立职责明确的共享模块，并显式从
packages/api导出。 - 仅复用请求/响应结构：使用
packages/api/models中的生成类型。
当前 PC UI 仓库是否包含移动端？
不包含。当前 workspace 只有：
apps/pc
apps/seller
apps/admin
packages/decor 中存在 mobile 装修预览能力，配置中也有 VITE_DOMAIN_MOBILE，但它们用于跨端数据和链接协作，不等于移动端应用已经包含在本仓库。移动端的源码、构建和发布必须按独立工程验证。
构建通过是否代表功能已经验收？
不代表。构建只能证明源码可以生成静态产物。发布或交付前还应至少验证：
- 登录、退出和刷新 token。
- 平台端、商家端在不同角色下的动态菜单。
- 直接打开和刷新二级路由。
- API、上传、CDN 和实时消息地址。
- 功能开关和多语言。
- 浏览器控制台没有未处理错误或资源 404。