fix: guard settings category render errors

Author: ZhuLinsen

apps/dsa-web/src/pages/SettingsPage.tsx

@@ -1,5 +1,5 @@
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { Component, useEffect, useRef, useState } from 'react';
 import { useAuth, useSystemConfig } from '../hooks';
 import { createParsedApiError, getParsedApiError, type ParsedApiError } from '../api/error';
 import { systemConfigApi } from '../api/systemConfig';
@@ -17,7 +17,7 @@ import {
   SettingsSectionCard,
 } from '../components/settings';
 import { WEB_BUILD_INFO } from '../utils/constants';
-import { getCategoryDescriptionZh } from '../utils/systemConfigI18n';
+import { getCategoryDescriptionZh, getCategoryTitleZh } from '../utils/systemConfigI18n';
 import type { SystemConfigCategory } from '../types/systemConfig';
 
 type DesktopWindow = Window & {
@@ -71,6 +71,64 @@ type DesktopUpdateNotice = {
   actionKind?: 'release' | 'install';
 };
 
+type SettingsContentErrorBoundaryProps = {
+  categoryTitle: string;
+  resetKey: string;
+  children: React.ReactNode;
+};
+
+type SettingsContentErrorBoundaryState = {
+  hasError: boolean;
+  message: string;
+};
+
+class SettingsContentErrorBoundary extends Component<
+  SettingsContentErrorBoundaryProps,
+  SettingsContentErrorBoundaryState
+> {
+  state: SettingsContentErrorBoundaryState = {
+    hasError: false,
+    message: '',
+  };
+
+  static getDerivedStateFromError(error: unknown): SettingsContentErrorBoundaryState {
+    return {
+      hasError: true,
+      message: error instanceof Error ? error.message : 'Unknown settings render error',
+    };
+  }
+
+  componentDidUpdate(previousProps: SettingsContentErrorBoundaryProps) {
+    if (previousProps.resetKey !== this.props.resetKey && this.state.hasError) {
+      this.setState({ hasError: false, message: '' });
+    }
+  }
+
+  componentDidCatch(error: unknown, info: unknown) {
+    console.error('Settings category render failed', error, info);
+  }
+
+  render() {
+    if (!this.state.hasError) {
+      return this.props.children;
+    }
+
+    const detail = this.state.message ? `错误信息：${this.state.message}。` : '';
+    return (
+      <SettingsSectionCard
+        title="当前分类加载失败"
+        description="该设置分类出现运行时异常，页面已保留其它导航与操作。"
+      >
+        <SettingsAlert
+          title={`${this.props.categoryTitle} 设置暂时无法显示`}
+          message={`${detail}请记录当前点击的设置分类，并提供 release 版本、Windows 版本和 desktop.log 继续排查。`}
+          variant="error"
+        />
+      </SettingsSectionCard>
+    );
+  }
+}
+
 function trimDesktopRuntimeString(value: unknown) {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -308,7 +366,12 @@ const SettingsPage: React.FC = () => {
     };
   }, [canCheckDesktopUpdate, desktopRuntimeApi]);
 
-  const rawActiveItems = itemsByCategory[activeCategory] || [];
+  const safeCategories = Array.isArray(categories) ? categories : [];
+  const safeItemsByCategory =
+    itemsByCategory && typeof itemsByCategory === 'object' ? itemsByCategory : {};
+  const rawActiveItems = Array.isArray(safeItemsByCategory[activeCategory])
+    ? safeItemsByCategory[activeCategory]
+    : [];
   const rawActiveItemMap = new Map(rawActiveItems.map((item) => [item.key, String(item.value ?? '')]));
   const hasConfiguredChannels = Boolean((rawActiveItemMap.get('LLM_CHANNELS') || '').trim());
   const hasLitellmConfig = Boolean((rawActiveItemMap.get('LITELLM_CONFIG') || '').trim());
@@ -365,6 +428,7 @@ const SettingsPage: React.FC = () => {
       : rawActiveItems;
   const isEnvBackupAllowed = isDesktopRuntime || authEnabled;
   const envBackupActionDisabled = isLoading || isSaving || isExportingEnv || isImportingEnv || !isEnvBackupAllowed;
+  const activeCategoryTitle = getCategoryTitleZh(activeCategory as SystemConfigCategory, activeCategory);
 
   const downloadEnvBackup = async () => {
     setEnvBackupActionError(null);
@@ -554,14 +618,18 @@ const SettingsPage: React.FC = () => {
         <div className="grid grid-cols-1 gap-5 lg:grid-cols-[280px_1fr]">
           <aside className="lg:sticky lg:top-4 lg:self-start">
             <SettingsCategoryNav
-              categories={categories}
-              itemsByCategory={itemsByCategory}
+              categories={safeCategories}
+              itemsByCategory={safeItemsByCategory}
               activeCategory={activeCategory}
               onSelect={setActiveCategory}
             />
           </aside>
 
           <section className="space-y-4">
+            <SettingsContentErrorBoundary
+              categoryTitle={activeCategoryTitle}
+              resetKey={activeCategory}
+            >
             {activeCategory === 'system' ? <AuthSettingsCard /> : null}
             {activeCategory === 'system' ? (
               <SettingsSectionCard
@@ -783,6 +851,7 @@ const SettingsPage: React.FC = () => {
                 className="settings-surface-panel settings-border-strong border-none bg-transparent shadow-none"
               />
             )}
+            </SettingsContentErrorBoundary>
           </section>
         </div>
       )}

apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx

@@ -21,6 +21,7 @@ const {
   applyPartialUpdate,
   refreshAfterExternalSave,
   refreshStatus,
+  settingsFieldThrowKey,
   useAuthMock,
   useSystemConfigMock,
   webBuildInfoMock,
@@ -41,6 +42,7 @@ const {
   applyPartialUpdate: vi.fn(),
   refreshAfterExternalSave: vi.fn(),
   refreshStatus: vi.fn(),
+  settingsFieldThrowKey: { value: '' },
   useAuthMock: vi.fn(),
   useSystemConfigMock: vi.fn(),
   webBuildInfoMock: {
@@ -139,7 +141,12 @@ vi.mock('../../components/settings', () => ({
       ))}
     </nav>
   ),
-  SettingsField: ({ item }: { item: { key: string } }) => <div>{item.key}</div>,
+  SettingsField: ({ item }: { item: { key: string } }) => {
+    if (settingsFieldThrowKey.value === item.key) {
+      throw new Error(`boom:${item.key}`);
+    }
+    return <div>{item.key}</div>;
+  },
   SettingsLoading: () => <div>loading</div>,
   SettingsSectionCard: ({
     title,
@@ -383,6 +390,7 @@ describe('SettingsPage', () => {
       refreshStatus,
     });
     useSystemConfigMock.mockReturnValue(buildSystemConfigState());
+    settingsFieldThrowKey.value = '';
     delete (window as { dsaDesktop?: unknown }).dsaDesktop;
     vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock');
     vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => undefined);
@@ -635,6 +643,22 @@ describe('SettingsPage', () => {
     expect(screen.getByText('WECHAT_WEBHOOK_URL')).toBeInTheDocument();
   });
 
+  it('keeps settings page usable when a category field throws during render', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    settingsFieldThrowKey.value = 'WECHAT_WEBHOOK_URL';
+    useSystemConfigMock.mockReturnValue(buildSystemConfigState({ activeCategory: 'notification' }));
+
+    render(<SettingsPage />);
+
+    expect(screen.getByRole('heading', { name: '系统设置' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'System' })).toBeInTheDocument();
+    expect(screen.getByText(/通知渠道 设置暂时无法显示/)).toBeInTheDocument();
+    expect(screen.getByText(/desktop\.log/)).toBeInTheDocument();
+    expect(screen.getByText(/boom:WECHAT_WEBHOOK_URL/)).toBeInTheDocument();
+
+    consoleErrorSpy.mockRestore();
+  });
+
   it('renders env backup actions outside desktop runtime', () => {
     render(<SettingsPage />);
 

docs/CHANGELOG.md

@@ -40,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [修复] 修正分析报告 API 构建策略点位时数值字段未归一为字符串的问题，避免策略价格触发响应 DTO 类型校验失败。
 - [修复] Docker 启动入口自动修复 `data` / `logs` / `reports` 挂载目录权限并降权运行，文档化的 Compose `exec` 手动命令显式使用 `dsa` 用户，避免普通部署需要手动 `chown` / `chmod`。
 - [修复] Web 首页大盘复盘结果改由主内容滚动区承载，避免 loading 切换到长结果后下方报告区域被截断或无法继续滚动。
+- [修复] Web/桌面设置页为当前分类增加局部运行时异常兜底，避免通知或 Agent 设置渲染异常时整页黑屏，并提示收集桌面端日志。
 
 ## [3.16.0] - 2026-05-10