JavaScript import() 实现路由懒加载的代码示例

在单页应用程序（SPA）中，路由懒加载是一种按需下载目标页面脚本的技术。它的核心目的是将整站庞大的单个 JavaScript 文件拆分成多个轻量分块（Chunks），当用户切换至对应路由路径时，浏览器才发起网络请求动态获取该页面代码，从而大幅削减首屏加载体积与首屏渲染延迟时间。

一、核心机制：静态 import 与动态 import() 的差异

ECMAScript 早期引入的静态 import ... from '...' 必须声明在模块顶层，构建工具（如 Webpack、Vite、Rollup）在静态分析依赖树时会将所有静态引用的模块全部打包至同一个或少数几个基础文件中。这意味着即使用户只访问首页，也会被迫预先下载设置页、详情页、后台管理页等所有未访问页面的逻辑代码。

ECMAScript 2020（ES11）标准化的类函数语法 import(modulePath) 则打破了静态限制。它可以在代码的任意位置按条件执行，并且无论何时调用，都会返回一个 Promise 对象。当脚本下载并解析完毕后，Promise 的状态变为已兑现（Resolved），并返回包含模块全部导出项的命名空间对象。构建工具在识别到 import() 语法调用时，会自动将该模块路径下的代码抽离为独立的文件碎片（Chunk）。

二、原生 JavaScript 单页路由中的实现示例

为了直观展示路由懒加载的底层运作方式，我们可以编写一个不依赖任何前端框架的原生单页哈希路由系统。路由表中的组件不直接保存 DOM 对象，而是保存返回 import() 调用的函数。

// 1. 路由表定义：component 字段为返回 Promise 的动态导入函数
const routes = {
  '#/home': {
    title: '首页',
    component: () => import('./views/home.js')
  },
  '#/about': {
    title: '关于我们',
    component: () => import('./views/about.js')
  },
  '#/dashboard': {
    title: '控制台',
    component: () => import('./views/dashboard.js')
  }
};

// 2. 核心路由处理函数
async function router() {
  const appContainer = document.getElementById('app');
  const currentHash = window.location.hash || '#/home';
  const targetRoute = routes[currentHash];

  if (!targetRoute) {
    appContainer.innerHTML = '<h2>404 - 页面未找到</h2>';
    return;
  }

  // 展示过渡状态，避免网络延迟时界面无响应
  appContainer.innerHTML = '<div class="loading">正在加载页面资源...</div>';

  try {
    // 关键调用：仅当哈希匹配时，才触发 import() 请求下载对应 JS 文件
    const module = await targetRoute.component();
    
    // 获取页面模块默认导出的 render 函数或模板字符串
    if (typeof module.default === 'function') {
      appContainer.innerHTML = '';
      appContainer.appendChild(module.default());
    } else {
      appContainer.innerHTML = module.default;
    }
    
    document.title = targetRoute.title;
  } catch (error) {
    appContainer.innerHTML = `<div class="error">加载失败：${error.message}</div>`;
  }
}

// 3. 监听 URL 变化与初次载入
window.addEventListener('hashchange', router);
window.addEventListener('DOMContentLoaded', router);

在子模块文件（例如 ./views/about.js）中，我们采用标准 ES Module 导出：

// ./views/about.js
export default function renderAboutView() {
  const section = document.createElement('section');
  section.innerHTML = `
    <h2>关于我们</h2>
    <p>本视图仅在 URL 匹配 #/about 时才由浏览器拉取并执行。</p>
  `;
  return section;
}

三、主流前端框架中的代码实现

1. Vue Router 4 中的写法

Vue Router 原生支持异步组件。将 component 属性指定为一个返回 import() 的箭头函数，Vue Router 会在首次导航到该路由时自动解析它：

import { createRouter, createWebHistory } from 'vue-router';

// 基础主包页面可使用同步导入（可选）
import HomeView from '../views/HomeView.vue';

const routes = [
  {
    path: '/',
    name: 'home',
    component: HomeView
  },
  {
    path: '/user-profile',
    name: 'profile',
    // 路由懒加载：仅在访问 /user-profile 时才拉取组件
    component: () => import('../views/UserProfile.vue')
  },
  {
    path: '/analytics',
    name: 'analytics',
    // Webpack Magic Comments：指定分包后的 chunk 命名（Vite 可通过 rollup 配置）
    component: () => import(/* webpackChunkName: "group-analytics" */ '../views/Analytics.vue')
  }
];

const router = createRouter({
  history: createWebHistory(),
  routes
});

export default router;

2. React Router 中的 React.lazy 与 Suspense 结合

在 React 中，动态 import() 通常通过 React.lazy() 包装，并且必须与 <Suspense> 协同工作，提供加载期间的回退 UI（Fallback）：

import React, { Suspense, lazy } from 'react';
import { BrowserRouter, Routes, Route, Link } from 'react-router-dom';

// 懒加载组件：必须是 default export
const Home = lazy(() => import('./routes/Home'));
const Settings = lazy(() => import('./routes/Settings'));
const Report = lazy(() => import('./routes/Report'));

function PageLoading() {
  return <div style={{ padding: '20px', color: '#687D8D' }}>正在加载页面，请稍候...</div>;
}

export default function App() {
  return (
    <BrowserRouter>
      <nav>
        <Link to="/">首页</Link> | 
        <Link to="/settings">设置</Link> | 
        <Link to="/report">报表</Link>
      </nav>

      {/* Suspense 捕获懒加载组件的 pending 状态 */}
      <Suspense fallback={<PageLoading />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/settings" element={<Settings />} />
          <Route path="/report" element={<Report />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

四、网络抖动与版本发布的异常重试处理

懒加载将脚本请求推迟到了运行时。如果遇到客户端网络瞬间波动、CDN 节点偶发异常，或者服务端完成新版本部署导致旧版本哈希 Hash 文件被移除（常见报错为 Failed to fetch dynamically imported module 或 ChunkLoadError），页面切换就会崩溃。

为了保障生产环境稳定性，不能简单地直接裸调 import()，而应当封装带有重试和降级策略的高阶函数：

/**
 * 带自动重试与版本容灾的动态 import 封装
 * @param {Function} importFn 返回 import() 调用的工厂函数
 * @param {number} retriesRemaining 剩余重试次数
 * @param {number} interval 间隔时间（毫秒）
 */
function lazyLoadWithRetry(importFn, retriesRemaining = 2, interval = 1000) {
  return new Promise((resolve, reject) => {
    importFn()
      .then(resolve)
      .catch((error) => {
        // 判断是否还有重试机会
        if (retriesRemaining > 0) {
          setTimeout(() => {
            console.warn(`[路由加载警告] 加载失败，剩余重试次数: ${retriesRemaining - 1}`);
            lazyLoadWithRetry(importFn, retriesRemaining - 1, interval).then(resolve, reject);
          }, interval);
        } else {
          // 重试仍失败，极可能是应用重新发版导致旧静态资源 404
          const hasReloaded = window.sessionStorage.getItem('chunk_reload_flag');
          if (!hasReloaded) {
            window.sessionStorage.setItem('chunk_reload_flag', 'true');
            // 刷新页面重新请求最新 HTML 与最新 chunk 依赖
            window.location.reload();
          } else {
            window.sessionStorage.removeItem('chunk_reload_flag');
            reject(error);
          }
        }
      });
  });
}

// 在路由配置中使用：
const routes = [
  {
    path: '/dashboard',
    component: () => lazyLoadWithRetry(() => import('./views/Dashboard.vue'))
  }
];

五、生产环境实施规范与避坑要点

考量维度	推荐做法	不推荐或错误做法
动态路径参数	import(`./views/${name}.js`) 保持前缀与后缀静态	import(variablePath) 完全纯变量路径（导致打包器无法分析或将整盘文件打包）
分包颗粒度	按业务页面模块或一级菜单拆分	为每个几十行的微型子组件都设置懒加载（增加过多 HTTP 请求开销）
预加载机制	对核心流程下级页面使用 prefetch 或在空闲时段预取	完全不配置预取，导致用户每次点击都需等待数十至数百毫秒网络延迟