ESM 动态 import 失败时如何显示降级界面

页面按需加载一个功能模块时，import() 返回的是 Promise。网络中断、文件 404、CORS 配置不正确，或模块初始化代码抛错，都会让这个 Promise 进入 rejected 状态。可靠的处理方式是把动态 import 放进一个可重复调用的函数，在 catch 中切换到降级界面，并保留一个真正会再次调用该函数的“重试”按钮。

为什么动态 import 失败后页面会突然没有内容

静态 import 通常在模块初始化阶段就参与加载，而动态 import() 是异步表达式，成功时得到模块命名空间对象，加载或模块求值失败时则 rejected。它不会同步抛出异常，所以只写 try/catch 包住调用却不使用 await，往往捕获不到 Promise rejection。

先把“加载模块”和“更新界面”拆开。这样无论失败发生在请求阶段、链接阶段还是模块执行阶段，页面都能进入同一个可恢复状态。

先封装一个每次都能重新调用的加载函数

示例用一个功能面板承载动态模块。loadFeature() 每执行一次都会产生新的动态导入链；成功后读取模块导出的 mount，失败后由统一的 showFallback() 接管。

const panel = document.querySelector('#feature-panel');
const retryButton = document.querySelector('#retry-feature');
let loading = false;

async function loadFeature() {
  if (loading) return; // 防止连续点击并发加载同一模块
  loading = true;
  retryButton.disabled = true; // 请求期间不允许重复提交
  panel.replaceChildren(document.createTextNode('功能加载中…'));

  try {
    const feature = await import('./feature-panel.js'); // 每次调用都重新进入加载流程
    panel.replaceChildren();
    feature.mount(panel); // 只把容器交给模块，避免模块直接改全局页面
  } catch (error) {
    console.error('动态模块加载失败', error); // 保留原始错误，便于定位 404、CORS 或执行异常
    showFallback();
  } finally {
    loading = false; // 成功或失败都必须解锁重试按钮
    retryButton.disabled = false;
  }
}

function showFallback() {
  panel.replaceChildren();
  const message = document.createElement('p');
  message.textContent = '功能暂时无法加载，请检查网络后重试。';
  panel.append(message);
  retryButton.hidden = false; // 降级界面保留恢复入口
}

retryButton.addEventListener('click', loadFeature); // 重试时重新调用 import()
loadFeature();

降级界面必须能恢复，而不是只显示一行错误

降级状态至少需要三件事：用户看得懂的提示、一个可以再次触发加载的按钮，以及不会遮蔽下一次成功结果的清理逻辑。replaceChildren() 用来移除上一次的加载态或错误文案，finally 则保证按钮不会因为异常永久禁用。

如果这个模块是路由页面的一部分，可以把错误状态放在当前内容区域；不要在失败时直接刷新整个页面。刷新会丢失用户上下文，也会把“可重试”变成一次代价更高的重新启动。

function showFallback(error) {
  panel.replaceChildren(); // 清除旧模块残留，避免错误和旧内容叠加
  const box = document.createElement('section');
  box.className = 'module-fallback';
  box.innerHTML = '
功能暂时不可用
可以稍后再次尝试。
';
  retryButton.textContent = '重新加载'; // 明确按钮会做什么
  box.append(retryButton);
  panel.append(box);
  if (error) console.error(error); // 用户界面不暴露内部路径和堆栈
}

生产代码中不要把完整错误堆栈直接插入 DOM。错误信息可以进入日志系统，界面只保留下一步动作。若部署后持续出现 Failed to fetch dynamically imported module，优先检查构建产物路径、静态资源缓存、CORS 和响应的 JavaScript MIME 类型。

重试次数与缓存问题怎么划边界

不要为了“让重试生效”就给模块 URL 随意拼接时间戳。模块成功加载后，运行时会缓存对应的模块命名空间；对网络加载失败，下一次导入通常会再次尝试，但最终是否命中 HTTP 缓存仍由浏览器和服务器的缓存语义决定。只有确实需要重新求值且能接受长期运行内存成本时，才考虑带版本参数的模块策略。

常见问题

只写 try/catch 为什么还捕获不到错误？

因为 import() 返回 Promise。使用 await import() 时，包住它的异步函数才能进入 catch；使用链式写法则应接上 .catch()。

点击重试后为什么界面一直是加载中？

常见原因是只在成功分支恢复按钮，失败分支提前返回。把解锁逻辑放进 finally，并确认没有遗留的 loading 标记。

动态 import 失败要不要自动重试？

网络类偶发错误可以有限重试；404、CORS 或模块执行错误不会因快速重复请求解决。建议先展示人工重试，并在日志中保留失败原因。