makemd/docs/ARCHIVE/05_AI/09_Frontend_Common_Issues.md

前端常见问题与解决方案

本文档记录前端开发过程中遇到的常见问题及其解决方案，供 AI 和开发者参考。

---

目录

1. 白屏问题
2. 图标问题
3. 路由配置问题
4. 组件导出问题
5. 编码问题
6. Ant Design 弃用警告

---

1. 白屏问题

1.1 症状

• 页面加载后显示空白
• 浏览器控制台显示 net::ERR_ABORTED 错误
• 页面无法正常渲染

1.2 常见原因

原因 1：路由未定义

问题：布局文件中的菜单链接指向未在 .umirc.ts 中定义的路由。

解决方案： 在 .umirc.ts 中添加缺失的路由配置：

routes: [
  // 确保所有菜单链接都有对应的路由
  {
    path: '/dashboard/ai-suggestion',
    component: '@/pages/AISuggestionPage',
  },
  // ... 其他路由
],

原因 2：组件导入错误

问题：组件文件使用了错误的导出方式，导致导入失败。

解决方案： 确保组件使用正确的导出方式：

// ❌ 错误：同时使用 export const 和 export default
export const MyComponent: React.FC = () => { ... };
export default MyComponent;

// ✅ 正确：只使用 export default
const MyComponent: React.FC = () => { ... };
export default MyComponent;

原因 3：图标不存在

问题：使用了 @ant-design/icons 中不存在的图标。

解决方案： 替换为存在的图标：

// ❌ 错误：BrainOutlined 不存在
import { BrainOutlined } from '@ant-design/icons';

// ✅ 正确：使用 RobotOutlined
import { RobotOutlined } from '@ant-design/icons';

---

2. 图标问题

2.1 症状

• 页面白屏
• 控制台显示 Element type is invalid 错误
• 图标无法显示

2.2 常见问题图标

问题图标	替代图标	说明
BrainOutlined	RobotOutlined	AI 相关功能
MindOutlined	BulbOutlined	思维/想法相关

2.3 批量替换命令

# 搜索所有使用 BrainOutlined 的文件
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | Select-String -Pattern "BrainOutlined"

# 批量替换（注意：必须使用 UTF-8 编码）
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | ForEach-Object { 
  $content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
  if ($content -match 'BrainOutlined') {
    $newContent = $content -replace 'BrainOutlined', 'RobotOutlined'
    [System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
    Write-Host "Fixed: $($_.Name)"
  }
}

---

3. 路由配置问题

3.1 症状

• 访问页面返回 404
• 页面白屏，显示 net::ERR_ABORTED
• 菜单链接无法跳转

3.2 路由配置规范

// .umirc.ts
export default defineConfig({
  routes: [
    // 根路由
    {
      path: '/',
      component: '@/pages/Homepage',
    },
    // Dashboard 路由
    {
      path: '/dashboard',
      component: '@/pages/DashboardPage',
    },
    // 子路由（必须完整定义）
    {
      path: '/dashboard/ai-suggestion',
      component: '@/pages/AISuggestionPage',
    },
    // ... 其他路由
  ],
});

3.3 路由与组件对应关系

路由路径	组件文件	说明
/dashboard/ai-suggestion	AISuggestionPage.tsx	AI 建议页面
/dashboard/human-approval	HumanApprovalPage.tsx	人工审批页面
/dashboard/execution-results	ExecutionResults.tsx	执行结果页面
/dashboard/client-management	ClientManagement.tsx	客户管理页面

---

4. 组件导出问题

4.1 症状

• 页面白屏
• 控制台显示 Element type is invalid 错误
• 组件无法正常渲染

4.2 正确的导出方式

// ❌ 错误：同时使用 export const 和 export default
export const MyComponent: React.FC = () => {
  return <div>My Component</div>;
};
export default MyComponent;

// ✅ 正确：只使用 export default
const MyComponent: React.FC = () => {
  return <div>My Component</div>;
};
export default MyComponent;

// ✅ 正确：命名导出（用于工具函数）
export const helperFunction = () => {
  return 'helper';
};

4.3 批量修复命令

# 修复所有使用 export const 的组件文件
Get-ChildItem -Path "src\pages" -Recurse -Filter "*.tsx" | ForEach-Object { 
  $content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
  if ($content -match 'export const (\w+): React\.FC') {
    $newContent = $content -replace 'export const (\w+): React\.FC', 'const $1: React.FC'
    [System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
    Write-Host "Fixed: $($_.Name)"
  }
}

---

5. 编码问题

5.1 症状

• 中文字符显示为乱码
• 编译错误：Unterminated string literal
• 文件内容损坏

5.2 原因

PowerShell 的 Set-Content 命令默认使用系统编码（通常是 GBK），而不是 UTF-8。

5.3 正确的文件读写方式

# ❌ 错误：使用 Set-Content（会损坏中文）
$content = Get-Content $_.FullName -Raw
Set-Content -Path $_.FullName -Value $newContent

# ✅ 正确：使用 .NET API 并指定 UTF-8 编码
$content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
[System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)

5.4 恢复损坏的文件

# 使用 Git 恢复文件
git checkout -- src/pages

---

6. Ant Design 弃用警告

6.1 Drawer visible 弃用

警告信息：

Warning: [antd: Drawer] `visible` is deprecated. Please use `open` instead.

解决方案：

// ❌ 旧写法
<Drawer visible={visible} onClose={onClose}>
  Content
</Drawer>

// ✅ 新写法
<Drawer open={visible} onClose={onClose}>
  Content
</Drawer>

批量修复命令：

Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | ForEach-Object { 
  $content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
  if ($content -match 'visible=\{') {
    $newContent = $content -replace 'visible=\{', 'open={'
    [System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
    Write-Host "Fixed: $($_.Name)"
  }
}

6.2 Dropdown overlay 弃用

警告信息：

Warning: [antd: Dropdown] `overlay` is deprecated. Please use `menu` instead.

解决方案：

// ❌ 旧写法
<Dropdown overlay={<Menu>...</Menu>}>
  <Button>Menu</Button>
</Dropdown>

// ✅ 新写法
<Dropdown menu={{ items: [...] }}>
  <Button>Menu</Button>
</Dropdown>

6.2 Tabs.TabPane 弃用

警告信息：

Warning: [antd: Tabs] `Tabs.TabPane` is deprecated. Please use `items` instead.

解决方案：

// ❌ 旧写法
<Tabs>
  <Tabs.TabPane tab="Tab 1" key="1">Content 1</Tabs.TabPane>
  <Tabs.TabPane tab="Tab 2" key="2">Content 2</Tabs.TabPane>
</Tabs>

// ✅ 新写法
<Tabs 
  items={[
    { label: 'Tab 1', key: '1', children: 'Content 1' },
    { label: 'Tab 2', key: '2', children: 'Content 2' },
  ]}
/>

6.3 Form.Item defaultValue 警告

警告信息：

Warning: [antd: Form.Item] `defaultValue` will not work on controlled Field. You should use `initialValues` of Form instead.

解决方案：

// ❌ 错误：在 Form.Item 中使用 defaultValue
<Form.Item name="field" defaultValue="value">
  <Input />
</Form.Item>

// ✅ 正确：在 Form 中使用 initialValues
<Form initialValues={{ field: 'value' }}>
  <Form.Item name="field">
    <Input />
  </Form.Item>
</Form>

---

7. React Hooks 错误

7.1 Invalid hook call

错误信息：

Warning: Invalid hook call. Hooks can only be called inside of the body of a function component.

常见原因：

1. React 版本不匹配
2. 违反 Hooks 使用规则
3. 同一个应用中有多个 React 副本

7.2 图表库冲突

问题：同时使用 @ant-design/plots 和 @ant-design/charts 会导致 React Hooks 错误。

解决方案： 统一使用 @ant-design/charts：

# 批量替换
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | ForEach-Object { 
  $content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
  if ($content -match '@ant-design/plots') {
    $newContent = $content -replace '@ant-design/plots', '@ant-design/charts'
    [System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
    Write-Host "Fixed: $($_.Name)"
  }
}

7.3 图表组件内部警告

警告信息：

Warning: The tag <%s> is unrecognized in this browser.
ExpressionError: Unexpected character: }

原因：这是 @ant-design/charts 库内部渲染 SVG 元素时产生的警告，不影响页面功能。

状态：无需修复，这是库的内部行为。如果警告过多影响开发，可以考虑：

1. 升级 @ant-design/charts 到最新版本
2. 或者使用其他图表库（如 recharts、echarts）

7.4 懒加载组件问题

错误信息：

Warning: lazy: Expected the result of a dynamic import() call.
Error: Element type is invalid. Received a promise that resolves to: undefined.

原因：

1. Umi 框架的 MFSU（Module Federation Speed Up）特性与某些组件不兼容
2. 组件导出方式不正确
3. 组件文件路径错误

解决方案：

1. 检查组件导出方式：

// ❌ 错误：没有默认导出
export const MyComponent = () => { ... };

// ✅ 正确：使用默认导出
const MyComponent: React.FC = () => { ... };
export default MyComponent;

2. 检查路由配置：

// .umirc.ts
{
  path: '/dashboard/inventory',
  component: '@/pages/Inventory/index',  // 确保路径正确
}

3. 清除缓存并重启：

# 清除 Umi 缓存
rm -rf .umi node_modules/.cache

# 重启开发服务器
npm run dev

4. 禁用 MFSU（临时方案）：

// .umirc.ts
export default defineConfig({
  mfsu: false,
  // ... 其他配置
});

---

8. 快速排查清单

当遇到白屏问题时，按以下顺序排查：

1. 检查浏览器控制台

   • 是否有 JavaScript 错误？
   • 是否有网络请求失败？

2. 检查路由配置

   • 路由是否在 .umirc.ts 中定义？
   • 组件路径是否正确？

3. 检查组件导出

   • 是否同时使用了 export const 和 export default？
   • 导入语句是否正确？

4. 检查图标使用

   • 是否使用了不存在的图标？
   • 图标是否从 @ant-design/icons 正确导入？

5. 检查文件编码

   • 文件是否使用 UTF-8 编码？
   • 中文字符是否正常显示？

---

9. DataSource 抽象层规范

9.1 为什么需要 DataSource 抽象层

问题：直接在组件中硬编码 mock 数据会导致：

1. AI 上下文污染 - AI 无法区分真实业务逻辑和 mock 数据
2. 维护困难 - 数据分散在各个组件中，难以统一管理
3. 切换困难 - 从 mock 切换到真实 API 需要大量修改

解决方案：使用 DataSource 抽象层

9.2 正确的数据获取方式

// ❌ 错误：硬编码 mock 数据
const MyComponent: React.FC = () => {
  const mockData = [
    { id: 1, name: '商品1' },
    { id: 2, name: '商品2' },
  ];
  // ...
};

// ✅ 正确：使用 DataSource 抽象层
import { productDataSource } from '@/services/productDataSource';

const MyComponent: React.FC = () => {
  const [products, setProducts] = useState([]);
  
  useEffect(() => {
    productDataSource.list().then(data => setProducts(data));
  }, []);
  // ...
};

9.3 DataSource 文件规范

位置：src/services/*DataSource.ts

命名：[模块名]DataSource.ts

标记：所有 mock 实现必须包含标记：

/**
 * [MOCK-XXX] 模块名DataSource
 * AI注意: 这是Mock实现，不是真实业务逻辑
 * 仅在USE_MOCK=true时启用
 */

9.4 现有 DataSource 列表

模块	DataSource 文件	状态
商品	productDataSource.ts	✅ 已实现
订单	orderDataSource.ts	✅ 已实现
库存	inventoryDataSource.ts	✅ 已实现
财务	financeDataSource.ts	✅ 已实现
分析	analyticsDataSource.ts	✅ 已实现
物流	logisticsDataSource.ts	✅ 已实现
供应商	suppliersDataSource.ts	✅ 已实现
用户	userDataSource.ts	✅ 已实现
设置	settingsDataSource.ts	✅ 已实现
广告	adOptimizationDataSource.ts	✅ 已实现

9.5 待改进的页面（使用硬编码 mock 数据）

以下 35 个页面使用了硬编码 mock 数据，需要迁移到 DataSource 抽象层：

页面	文件路径
AI 决策日志	AIDecisionLog/index.tsx
订单管理	Orders/index.tsx
异常订单	Orders/ExceptionOrder.tsx
任务中心	TaskCenter/index.tsx
报表	Reports/index.tsx
执行结果	ExecutionResults.tsx
人工审批	HumanApprovalPage.tsx
AI 任务管理	AIActionTaskManager.tsx
运营代理增强	OperationAgentEnhanced.tsx
B2B 批量订单	B2B/BatchOrder.tsx
B2B 合同管理	B2B/ContractManage.tsx
B2B 企业报价	B2BTrade/EnterpriseQuote.tsx
B2B 贸易合同	B2BTrade/ContractManage.tsx
售后退款	AfterSales/RefundProcess.tsx
客户服务	AfterSales/CustomerService.tsx
平台账户配置	Settings/PlatformAccountConfig.tsx
系统设置	Settings/SystemSettings.tsx
用户管理	Settings/UserManagement.tsx
成本模板配置	Settings/CostTemplateConfig.tsx
Win 节点配置	Settings/WinNodeConfig.tsx
汇率配置	Settings/ExchangeRateConfig.tsx
供应商详情	Suppliers/SupplierDetail.tsx
域名管理	IndependentSite/DomainManagement.tsx
独立站订单	IndependentSite/IndependentSiteOrder.tsx
竞品分析	Marketing/Competitors.tsx
广告自动调整	Ad/AutoAdjustment/index.tsx
AI 优化	Ad/AIOptimization/index.tsx
广告效果	Ad/Performance/index.tsx
AI 定价	Product/AIPricing/index.tsx
ROI 分析	Product/ROIAnalysis/index.tsx
利润监控	Product/ProfitMonitor/index.tsx
利润报表	Reports/ProfitReport.tsx
绩效报表	Reports/PerformanceReport.tsx
库存预测	Inventory/InventoryForecast.tsx
批量上架	OperationAgent/components/ProductBatch/BatchListingModal.tsx

---

10. 相关文档

• TypeScript 编译规约
• 代码质量规范
• 前端开发指南
• Mock 架构设计

---

最后更新：2026-03-26