Vite SSR服务端渲染引入react-live-runner时出现模块导入语法错误

问题场景 #

• 基于vite-plugin-ssr的React+Redux示例项目，集成react-live-runner包时遇到SSR报错
• 操作流程：
  1. 拉取vite-plugin-ssr的React+Redux示例项目
  2. 执行npm install && npm install react-live-runner，启动后初始SSR服务正常
  3. 在index.page.jsx中导入react-live-runner，热重载下UI渲染正常
  4. 刷新浏览器触发SSR时，抛出错误：SyntaxError: Cannot use import statement outside a module
• 排查细节：react-live-runner的dist文件采用ES6模块语法，package.json的exports默认指向index.modern.js；手动给react-live-runner和react-runner的package.json添加"type": "module"后，又引发react-dom相关的新错误

解决方案 #

方法1：让Vite转译第三方包适配SSR #

Vite默认不转译node_modules里的包，SSR时Node环境无法识别ES6模块语法，需配置让Vite转译react-live-runner及其依赖react-runner。

修改vite.config.js，添加ssr.noExternal配置：

export default {
  ssr: {
    noExternal: ['react-live-runner', 'react-runner']
  }
}

配置后Vite会在SSR构建时把这两个包的ES6模块语法转为Node兼容的CommonJS格式，直接解决语法报错问题。

方法2：仅在客户端加载react-live-runner #

react-live-runner是实时交互组件，不需要在SSR阶段渲染，可通过动态导入仅在浏览器环境加载。

修改index.page.jsx：

import { useState, useEffect } from 'react';

function IndexPage() {
  const [LiveRunner, setLiveRunner] = useState(null);

  useEffect(() => {
    // 仅客户端环境动态导入组件
    import('react-live-runner').then(module => {
      setLiveRunner(module.LiveRunner);
    });
  }, []);

  if (!LiveRunner) {
    // SSR或加载中显示占位内容
    return <div>Loading...</div>;
  }

  return (
    <div>
      <LiveRunner
        code="console.log('Hello from react-live-runner')"
      />
    </div>
  );
}

export default IndexPage;

这种方式完全跳过SSR阶段对该组件的处理，从根源避免模块语法冲突。

方法3：切换项目为ES模块模式（谨慎使用） #

如果项目整体可以适配ES模块，可在项目根目录的package.json添加"type": "module"，同时将vite.config.js改为ES模块语法（或重命名为vite.config.mjs）：

// vite.config.mjs
export default {
  // 原有配置
}

但这种方式可能触发其他依赖的兼容问题（比如部分CommonJS包无法正常导入），需要逐一排查适配，优先推荐前两种方法。

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