--- name: jjb-troubleshooting description: 开发与生产环境常见故障排查指南。覆盖接口返回 HTML、菜单加载失败、权限/字段重命名配置不同步、应用版本信息检查、本地联调、底座 API 调用、Java 集成构建产物、表单引擎调试等场景。 --- # 应用配置与开发环境 ## 故障排查 ### 接口返回 HTML 页面 **现象**：开发环境接口调用正常，生产环境接口响应返回 HTML 页面内容。 **可能原因及解决方案**： | 原因 | 说明 | 解决方向 | |------|------|---------| | 后端服务未启动 | 接口服务未正常运行，请求无法命中接口地址，被重定向至底座默认页面 | 检查后端服务部署与运行状态 | | 代码同步问题 | 后端代码未同步到对应环境，接口路由丢失 | 确认后端代码已部署至目标环境 | | 前端接口地址配置错误 | 接口地址拼写错误或配置不正确 | 检查接口 baseURL 与环境变量配置 | > **建议**：优先检查后端服务状态，此类问题通常与后端部署相关。 ### 接口常见状态码 | 状态码 / Code | 含义 | 开发阶段排查 | |--------------|------|-------------| | **401** | 未授权，即未登录 | 检查接口是否请求头是否携带token，或检查浏览器中 `sessionStorage.token` 是否已设置； | | **500 / 503** | 服务端错误，通常为后端重启中 | 等待片刻后重试，若持续出现则需后端排查 | | `BIZ_ERROR` | 接口服务内部代码错误 | 联系后端排查业务逻辑，非前端问题 | ### 应用菜单加载失败 **现象**：在底座平台中打开应用菜单时提示「当前页面加载失败」。 **排查顺序**： 1. **后端服务状态** — 确认应用后端服务是否正常启动运行 2. **前端资源加载** — 检查静态资源是否正常加载，排查跨域或资源路径问题 3. **构建产物完整性** — 验证 `dist` 构建产物是否完整，`static/` 目录资源是否存在缺失 > **建议**：按上述顺序逐步验证，前后端协同排查。 ### 环境间配置同步 各环境的配置数据**独立存储**，发布到新环境时不会自动同步。 | 配置类型 | 现象 | 原因 | 解决方案 | |---------|------|------|---------| | 按钮权限 | 开发环境配置的权限在其他环境不生效 | 权限配置按环境隔离 | 通知后端运维同步权限数据 | | 字段重命名 | 开发环境配置的字段重命名在其他环境不生效 | 字段重命名按环境隔离 | 通知后端运维同步配置数据 | > 发布到新环境时，**主动通知**后端运维进行配置数据同步操作。 ### 应用版本信息检查 #### 方法一：浏览器控制台 每个应用菜单打开时会在控制台输出构建信息，包含： - 构建工具版本 - 前端构建环境 - 应用唯一标识符（`appIdentifier`） - 前后端代码分支信息 - 打包构建日期 #### 方法二：HTML 源码分析 应用构建时在 HTML `` 标签中注入 `data-built-info` 属性： 1. 打开浏览器开发者工具 2. 切换到 **Network** 面板 3. 找到目标应用的文档请求 4. 查看 Response 中 HTML 源码，定位 `data-built-info` 属性值 #### 构建信息格式差异 不同应用显示的构建信息格式或内容可能存在差异。原因：微应用基于 `@cqsjjb/scripts` 依赖包构建，各应用使用的依赖版本不同，输出格式存在差异。此属正常现象，不影响功能。 ### 本地开发环境联调 替换线上应用进行本地调试： 1. 在底座平台打开目标应用菜单 2. 控制台获取应用配置：`sessionStorage.BASE_MODULE_MONITOR` 3. 在配置项 `items` 中找到目标菜单 4. 将 `data-app-entry` 修改为本地服务地址（如 `http://localhost:8080/system`） 5. 将修改后的配置重新设置到 `sessionStorage` 6. 刷新页面，即可在线上环境调试本地应用 ### 底座 API 调用 #### 开发阶段限制 在**独立开发环境**中直接调用底座 API 会失败并抛异常。调用前必须通过 `window.__IN_BASE__` 判断当前运行环境： ```js if (window.__IN_BASE__) { // 调用底座 API } else { // 使用 mock 数据 } ``` #### 开发阶段模拟方案 1. 在线上环境通过控制台调用目标 API，获取响应数据格式 2. 在开发环境创建对应的 mock 数据模拟 API 响应 3. （后续计划）提供标准 API 模拟工具包 ### 接口认证 Token **机制**：使用 `@cqsjjb/jjb-common-lib/http.js` 发起的请求，会自动从 `sessionStorage.token` 获取并设置认证 Token。 **开发调试**：开发阶段需**手动设置** `sessionStorage.token` 值才能进行接口测试。 ### 前端应用 Java 集成 #### 构建产出要求 无论使用 Vite、Rollup 还是 Webpack，要正常集成到 Java 后端，必须满足： 1. **HTML 文件重命名** — `index.html` 必须重命名为唯一标识名称（如 `system.html`） 2. **静态资源目录结构** — 所有静态资源必须放置在 `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），且小版本兼容。 ### 表单引擎调试 在底座平台控制台快速打开表单设计器： ```js base.plugin.openFormilyDesign(<设计代码>) ``` 1. 获取目标表单引擎的设计代码 2. 在控制台执行上述命令 3. 即可打开表单设计器进行配置调整 > ⚠️ **安全警告**：此操作具有较高风险，请谨慎使用，确保已备份原有配置。