159 lines
6.2 KiB
Markdown
159 lines
6.2 KiB
Markdown
|
---
|
|||
|
|
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 `<head>` 标签中注入 `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. 即可打开表单设计器进行配置调整
|
|||
|
|
|
|||
|
|
> ⚠️ **安全警告**：此操作具有较高风险，请谨慎使用，确保已备份原有配置。
|