错误码与解决办法

qiankun 自身抛出的 QiankunError 带有稳定的 code 属性，消息末尾附有对应解决方案的官网链接。

识别框架错误

ts

import { loadMicroApp, QiankunError } from 'qiankun';

const microApp = loadMicroApp({ name, entry, container });

void microApp.mountPromise.catch((error: unknown) => {
  if (error instanceof QiankunError) {
    console.error(error.code, error.message);
  } else {
    console.error(error);
  }
});

loader、沙箱和共享模块抛出的框架错误都是同一个 QiankunError 类的实例。微应用自身、浏览器或 single-spa 也可能抛出其他类型的错误，调用方应一并处理。

公开约定

ts

import { type QiankunErrorCode } from 'qiankun';

declare class QiankunError extends Error {
  readonly code: QiankunErrorCode;
}

对外承诺的只有两点：用 instanceof QiankunError 识别框架错误，以及只读的 code 属性。QiankunError 只由 qiankun 内部创建，构造函数不属于公开 API。message 末尾附有解决方案链接，链接统一指向中文页，各页提供英文入口。

错误码约定

错误码使用小写英文单词和连字符，按触发原因与解决方法命名。同一原因在不同包出现时共用错误码；文件移动、文案调整或新增其他错误均不改变已有错误码。程序判断请使用 error.code，避免依赖完整错误消息。

错误码索引