前言
你有没有遇到过这种情况:用户在某个页面点了个按钮,接口超时了,页面直接白屏,然后应用闪退。查日志发现是一个未捕获的 Promise rejection。
这类问题在鸿蒙应用里也很常见。错误处理如果只是到处写 try-catch,不仅代码臃肿,还容易漏掉。这篇文章我来搭一套全局错误处理架构,从捕获、分类、降级到上报,一条龙解决。
鸿蒙应用的错误分类
先理清楚错误有哪些类型,不同类型处理方式不一样:
- 同步错误:代码逻辑出错,比如空指针、数组越界。这类最致命,通常会导致页面崩溃。

- 异步错误:Promise rejection 没被 catch,或者 async 函数里抛了异常。
- 网络错误:超时、断网、服务端 5xx。这类最常见,也是最能优化体验的地方。
- 系统错误:权限被拒、存储空间不足、传感器不可用。这类需要引导用户去设置。
全局错误捕获
鸿蒙提供了 globalThis 上的错误监听能力,我在应用启动时就注册好:
// entry/src/main/ets/entryability/EntryAbility.ts
import { ErrorHandler } from '../common/ErrorHandler';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// 注册全局错误捕获
ErrorHandler.setup();
// 初始化日志、网络层等
Logger.info('App', '应用启动');
}
}
ErrorHandler 是核心类,负责注册各类错误监听并分发处理:
import { ErrorReporter } from './ErrorReporter';
import { ErrorMessageMapper } from './ErrorMessageMapper';
export interface AppError {
type: 'sync' | 'async' | 'network' | 'system';
code: number;
message: string;
stack?: string;
timestamp: number;
pageName?: string;
}
export class ErrorHandler {
private static handlers: Array<(error: AppError) => void> = [];
static setup(): void {
// 捕获未处理的同步错误
globalThis.onerror = (msg: string, source: string, lineno: number, colno: number, error: Error) => {
const appError: AppError = {
type: 'sync',
code: -1,
message: msg,
stack: error?.stack,
timestamp: Date.now()
};
ErrorHandler.dispatch(appError);
};
// 捕获未处理的 Promise rejection
globalThis.onunhandledrejection = (event: PromiseRejectionEvent) => {
const appError: AppError = {
type: 'async',
code: -2,
message: String(event.reason),
stack: event.reason?.stack,
timestamp: Date.now()
};
ErrorHandler.dispatch(appError);
// 阻止默认行为,防止应用崩溃
event.preventDefault?.();
};
Logger.info('ErrorHandler', '全局错误捕获已注册');
}
// 注册错误处理回调
static addHandler(handler: (error: AppError) => void): void {
this.handlers.push(handler);
}
// 分发错误到所有处理器
private static dispatch(error: AppError): void {
// 先上报
ErrorReporter.report(error);
// 再通知所有注册的处理器
for (const handler of this.handlers) {
try {
handler(error);
} catch (e) {
console.error('错误处理器自身出错', e);
}
}
}
// 手动上报错误(用于业务层主动上报)
static report(code: number, message: string, type: AppError['type'] = 'sync'): void {
const appError: AppError = {
type, code, message,
timestamp: Date.now()
};
this.dispatch(appError);
}
}

错误降级策略:三层兜底
核心思路是 接口失败 → 缓存兜底 → 兜底 UI,尽量不让用户看到白屏。
export type DataState<T> =
| { status: 'loading' }
| { status: 'success'; data: T }
| { status: 'cache'; data: T; stale: boolean }
| { status: 'error'; error: AppError };
export class DataFetcher<T> {
private cacheKey: string;
constructor(cacheKey: string) {
this.cacheKey = cacheKey;
}
async fetch(
requestFn: () => Promise<T>,
options?: { useCache?: boolean; cacheTTL?: number }
): Promise<DataState<T>> {
try {
const data = await requestFn();
// 请求成功,同时更新缓存
if (options?.useCache !== false) {
await this.saveCache(data);
}
return { status: 'success', data };
} catch (error) {
// 请求失败,尝试缓存兜底
if (options?.useCache !== false) {
const cached = await this.loadCache();
if (cached) {
Logger.warn('DataFetcher', `${this.cacheKey} 接口失败,使用缓存兜底`);
return { status: 'cache', data: cached.data, stale: true };
}
}
// 缓存也没有,返回错误状态
return {
status: 'error',
error: error as AppError
};
}
}
private async saveCache(data: T): Promise<void> {
const context = getContext() as common.UIAbilityContext;
const prefs = await preferences.getPreferences(context, 'data_cache');
await prefs.put(this.cacheKey, JSON.stringify({
data,
timestamp: Date.now()
}));
await prefs.flush();
}
private async loadCache(): Promise<{ data: T; stale: boolean } | null> {
try {
const context = getContext() as common.UIAbilityContext;
const prefs = await preferences.getPreferences(context, 'data_cache');
const raw = prefs.getSync(this.cacheKey, '') as string;
if (!raw) return null;
const parsed = JSON.parse(raw);
return { data: parsed.data as T, stale: true };
} catch {
return null;
}
}
}

错误码 → 用户可读文案
直接给用户看 “Error code: 40001” 没有任何意义。搞一个映射表,把错误码翻译成人话:
export class ErrorMessageMapper {
private static messages: Map<number, string> = new Map([
[10001, '网络连接失败,请检查网络设置'],
[10002, '请求超时,请稍后重试'],
[10003, '服务器开小差了,请稍后再试'],
[20001, '登录已过期,请重新登录'],
[20002, '账号在其他设备登录'],
[20003, '账号已被禁用'],
[30001, '内容不存在或已被删除'],
[30002, '没有权限执行此操作'],
[40001, '存储空间不足,请清理后重试'],
[40002, '相机权限未开启,请在设置中允许'],
]);
static getMessage(code: number): string {
return this.messages.get(code) ?? '出了点问题,请稍后重试';
}
// 注册新的错误码映射
static register(code: number, message: string): void {
this.messages.set(code, message);
}
}
ErrorBoundary 组件:错误隔离 + 降级 UI
借鉴 React 的 ErrorBoundary 思路,我实现了一个 ArkUI 版本的错误边界组件。核心是用 @State 控制显示状态,出错了就展示兜底 UI,不影响其他模块。
@Component
export struct ErrorBoundary {
@State hasError: boolean = false;
@State errorMessage: string = '';
@State errorDetail: string = '';
@Prop fallbackText: string = '加载失败';
onRetry?: () => void;
@BuilderParam content: () => void;
aboutToAppear(): void {
ErrorHandler.addHandler((error: AppError) => {
// 可以根据 pageName 判断是不是当前区域的错误
this.hasError = true;
this.errorMessage = ErrorMessageMapper.getMessage(error.code);
this.errorDetail = error.message;
});
}
build() {
if (this.hasError) {
Column() {
Image($r('app.media.ic_error'))
.width(80)
.height(80)
.margin({ bottom: 16 })
Text(this.errorMessage)
.fontSize(16)
.fontColor('#333333')
.margin({ bottom: 8 })
Text('点击重试')
.fontSize(14)
.fontColor('#007DFF')
.onClick(() => {
this.hasError = false;
this.onRetry?.();
})
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
} else {
Column() {
this.content()
}
}
}
}
使用方式很简单,把可能出错的区域包起来:
@Entry
@Component
struct ProductPage {
@State products: Product[] = [];
build() {
Column() {
// 头部不参与错误隔离
HeaderBar({ title: '商品列表' })
// 列表区域用 ErrorBoundary 包裹
ErrorBoundary({
onRetry: () => this.loadProducts(),
content: () => {
List() {
ForEach(this.products, (item: Product) => {
ListItem() { ProductCard({ product: item }) }
})
}
}
})
}
}
async loadProducts() {
const fetcher = new DataFetcher<Product[]>('products');
const result = await fetcher.fetch(
() => httpService.get<Product[]>('/products'),
{ useCache: true }
);
switch (result.status) {
case 'success':
case 'cache':
this.products = result.data;
if (result.status === 'cache') {
// 提示用户数据可能不是最新的
promptAction.showToast({ message: '当前显示离线数据' });
}
break;
case 'error':
ErrorHandler.report(result.error.code, result.error.message, 'network');
break;
}
}
}
错误上报
最后别忘了把错误发到服务端,方便排查问题。上报的时候带上设备信息、页面路径、用户 ID 这些上下文:
export class ErrorReporter {
private static reportUrl: string = 'https://log.example.com/report';
private static queue: AppError[] = [];
private static batchSize: number = 10;
static report(error: AppError): void {
this.queue.push(error);
if (this.queue.length >= this.batchSize) {
this.flush();
}
}
static async flush(): Promise<void> {
if (this.queue.length === 0) return;
const batch = this.queue.splice(0);
const deviceInfo = device.getCurrent();
const reportData = {
errors: batch,
device: deviceInfo.productModel,
osVersion: deviceInfo.osFullName,
appVersion: '1.0.0',
timestamp: Date.now()
};
try {
// 上报请求本身不能再触发错误上报,否则会死循环
await http.createHttp().request(this.reportUrl, {
method: http.RequestMethod.POST,
extraData: reportData,
connectTimeout: 5000,
});
} catch {
// 上报失败就丢掉,不能影响主流程
}
}
}
一些心得
搞完这套错误处理架构之后,我的项目稳定性提升了很多。几个关键点:
降级比报错重要。 用户不关心你的接口为什么挂了,他们只想知道还能不能用。缓存兜底 + 提示"离线数据",体验比白屏好太多了。
错误码映射表要维护好。 每加一个新接口就检查一下错误码是否有对应文案,别让用户看到 “undefined” 或 “Error: null”。
错误上报别阻塞主线程。 用队列批量上报,失败了就静默丢弃。上报请求本身绝对不能触发二次上报,不然一个网络抖动就能把日志打爆。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/qq_33681891/article/details/162408005




