如何在single-spa微前端框架中集成Next.js？

核心适配逻辑 #

single-spa要求微应用必须暴露bootstrap、mount、unmount三个核心生命周期钩子，而Next.js的路由、构建模式和普通React应用存在差异，所以核心是通过single-spa-next工具库让Next.js适配single-spa的生命周期规范，同时保留现有代码结构。

1. 安装依赖并配置Next.js项目 #

首先在你的Next.js微应用中安装必要依赖：

npm install single-spa-react single-spa-next

然后修改next.config.js，接入single-spa-next的配置插件：

const { withSingleSpa } = require('single-spa-next');

module.exports = withSingleSpa({
  singleSpaOptions: {
    baseUrl: '/next-microapp', // 微应用在主应用中的路由前缀
    name: 'next-microapp', // single-spa中注册的应用标识名
  },
  // 保留原有Next.js配置，比如webpack、环境变量等
});

2. 暴露single-spa生命周期钩子 #

根据你使用的Next.js路由模式（Pages Router/App Router）做对应改造：

针对Pages Router

修改pages/_app.js，用single-spa-react包裹根组件并导出生命周期：

import React from 'react';
import App from 'next/app';
import { singleSpaReact } from 'single-spa-react';

class MyApp extends App {
  render() {
    const { Component, pageProps } = this.props;
    return <Component {...pageProps} />;
  }
}

const lifecycles = singleSpaReact({
  React,
  ReactDOM: require('react-dom'),
  rootComponent: MyApp,
  errorBoundary(err, info, props) {
    // 自定义错误边界渲染内容
    return <div className="error">Next微应用加载失败</div>;
  },
});

// 导出single-spa所需的生命周期钩子
export const bootstrap = lifecycles.bootstrap;
export const mount = lifecycles.mount;
export const unmount = lifecycles.unmount;

针对App Router

在项目根目录创建single-spa-entry.js，通过single-spa-next绑定根布局并导出生命周期：

import { singleSpaNext } from 'single-spa-next';
import React from 'react';
import RootLayout from './app/layout';

const nextLifecycles = singleSpaNext({
  React,
  ReactDOM: require('react-dom'),
  nextApp: RootLayout,
  routerBase: '/next-microapp', // 和next.config.js中的baseUrl保持一致
});

export const bootstrap = nextLifecycles.bootstrap;
export const mount = nextLifecycles.mount;
export const unmount = nextLifecycles.unmount;

同时在app/[...catchAll]/page.js中添加路由兜底，确保Next.js能处理前缀内的所有路由：

import { useRouter } from 'next/router';

export default function CatchAllPage() {
  const router = useRouter();
  // 这里可以根据需要渲染对应内容，或者直接返回null让路由正常匹配
  return null;
}

3. 在single-spa主应用中注册Next微应用 #

在主应用的入口配置文件中，注册这个Next.js微应用：

import { registerApplication, start } from 'single-spa';

registerApplication({
  name: 'next-microapp', // 和Next项目中配置的name一致
  app: () => System.import('http://your-next-app-domain/next-microapp'), // Next应用的部署地址+前缀
  activeWhen: ['/next-microapp'], // 匹配该路由前缀时激活微应用
});

start();

4. 兼容现有React微应用的关键注意事项 #

• React版本统一：确保所有微应用使用的React、ReactDOM版本一致，若无法统一，可引入react-is库处理跨版本兼容问题
• 静态资源路径：Next.js的静态资源需配置正确的publicPath，避免在主应用中加载错误
• 路由隔离：通过routerBase严格限定Next微应用的路由范围，防止和其他微应用、主应用路由冲突
• 样式隔离：Next.js的全局样式建议使用CSS Modules或CSS-in-JS方案，避免污染全局样式；也可在unmount钩子中手动清理全局样式

内容的提问来源于stack exchange，提问作者Giovanni Smith