6.2 KiB

Raw Permalink Blame History

name	description
jjb-troubleshooting	开发与生产环境常见故障排查指南。覆盖接口返回 HTML、菜单加载失败、权限/字段重命名配置不同步、应用版本信息检查、本地联调、底座 API 调用、Java 集成构建产物、表单引擎调试等场景。

应用配置与开发环境

故障排查

接口返回 HTML 页面

现象：开发环境接口调用正常，生产环境接口响应返回 HTML 页面内容。

可能原因及解决方案：

原因	说明	解决方向
后端服务未启动	接口服务未正常运行，请求无法命中接口地址，被重定向至底座默认页面	检查后端服务部署与运行状态
代码同步问题	后端代码未同步到对应环境，接口路由丢失	确认后端代码已部署至目标环境
前端接口地址配置错误	接口地址拼写错误或配置不正确	检查接口 baseURL 与环境变量配置

建议：优先检查后端服务状态，此类问题通常与后端部署相关。

接口常见状态码

状态码 / Code	含义	开发阶段排查
401	未授权，即未登录	检查接口是否请求头是否携带token，或检查浏览器中 `sessionStorage.token` 是否已设置；
500 / 503	服务端错误，通常为后端重启中	等待片刻后重试，若持续出现则需后端排查
`BIZ_ERROR`	接口服务内部代码错误	联系后端排查业务逻辑，非前端问题

应用菜单加载失败

现象：在底座平台中打开应用菜单时提示「当前页面加载失败」。

排查顺序：

后端服务状态 — 确认应用后端服务是否正常启动运行
前端资源加载 — 检查静态资源是否正常加载，排查跨域或资源路径问题
构建产物完整性 — 验证 dist 构建产物是否完整，static/ 目录资源是否存在缺失

建议：按上述顺序逐步验证，前后端协同排查。

环境间配置同步

各环境的配置数据独立存储，发布到新环境时不会自动同步。

配置类型	现象	原因	解决方案
按钮权限	开发环境配置的权限在其他环境不生效	权限配置按环境隔离	通知后端运维同步权限数据
字段重命名	开发环境配置的字段重命名在其他环境不生效	字段重命名按环境隔离	通知后端运维同步配置数据

发布到新环境时，主动通知后端运维进行配置数据同步操作。

应用版本信息检查

方法一：浏览器控制台

每个应用菜单打开时会在控制台输出构建信息，包含：

构建工具版本
前端构建环境
应用唯一标识符（appIdentifier）
前后端代码分支信息
打包构建日期

方法二：HTML 源码分析

应用构建时在 HTML <head> 标签中注入 data-built-info 属性：

打开浏览器开发者工具
切换到 Network 面板
找到目标应用的文档请求
查看 Response 中 HTML 源码，定位 data-built-info 属性值

构建信息格式差异

不同应用显示的构建信息格式或内容可能存在差异。原因：微应用基于 @cqsjjb/scripts 依赖包构建，各应用使用的依赖版本不同，输出格式存在差异。此属正常现象，不影响功能。

本地开发环境联调

替换线上应用进行本地调试：

在底座平台打开目标应用菜单
控制台获取应用配置：sessionStorage.BASE_MODULE_MONITOR
在配置项 items 中找到目标菜单
将 data-app-entry 修改为本地服务地址（如 http://localhost:8080/system）
将修改后的配置重新设置到 sessionStorage
刷新页面，即可在线上环境调试本地应用

底座 API 调用

开发阶段限制

在独立开发环境中直接调用底座 API 会失败并抛异常。调用前必须通过 window.__IN_BASE__ 判断当前运行环境：

if (window.__IN_BASE__) {
  // 调用底座 API
} else {
  // 使用 mock 数据
}

开发阶段模拟方案

在线上环境通过控制台调用目标 API，获取响应数据格式
在开发环境创建对应的 mock 数据模拟 API 响应
（后续计划）提供标准 API 模拟工具包

接口认证 Token

机制：使用 @cqsjjb/jjb-common-lib/http.js 发起的请求，会自动从 sessionStorage.token 获取并设置认证 Token。

开发调试：开发阶段需手动设置 sessionStorage.token 值才能进行接口测试。

前端应用 Java 集成

构建产出要求

无论使用 Vite、Rollup 还是 Webpack，要正常集成到 Java 后端，必须满足：

HTML 文件重命名 — index.html 必须重命名为唯一标识名称（如 system.html）
静态资源目录结构 — 所有静态资源必须放置在 static/ 目录下，并被与 HTML 同名的文件夹包裹

标准目录结构

dist/
├── system.html          # 重命名后的入口文件
└── system/              # 与 HTML 同名的文件夹
    └── static/          # 静态资源目录
        ├── js/          # JavaScript 文件
        ├── css/         # 样式文件
        └── images/      # 图片资源

antd 与 @ant-design/icons 版本对齐

现象：antd 图标组件样式异常，或自定义 ant-prefix 未对图标生效。

原因：antd 与 @ant-design/icons 版本不匹配时，jjb.config.js 中 framework.antd['ant-prefix'] 无法透传至图标组件的 className，导致前缀不一致、样式丢失。

解决：确保 antd 与 @ant-design/icons 主版本对齐（均为 5.x），且小版本兼容。

表单引擎调试

在底座平台控制台快速打开表单设计器：

base.plugin.openFormilyDesign(<设计代码>)

获取目标表单引擎的设计代码
在控制台执行上述命令
即可打开表单设计器进行配置调整

⚠️ 安全警告：此操作具有较高风险，请谨慎使用，确保已备份原有配置。

6.2 KiB Raw Permalink Blame History Unescape Escape