Modern.js 2022 年 7~8 月版本更新深度解读：React 18 适配、包版本统一与 Module Bundle 构建

• 前端
• 后端
• Web框架

本篇基于官方双月更新公告（2022-0708-updates.md）编写，并结合当前仓库源码对各项能力的实现细节进行印证。

Modern.js 在 2022 年 7~8 月双月发布了 v1.17.0，核心变化包括：框架与插件体系全面适配 React 18、所有组成包版本号统一并配套自动升级工具、Modern.js Module 引入基于output.buildConfig的 bundle 构建能力、第一方状态管理方案 Reduck 发布 v1.1。读完本文，你将掌握 React 18 的升级路径、npx @modern-js/upgrade的使用方法、Module 项目buildType配置的写法，以及preEntry、inspect、afterLambdaRegisted、按入口设置响应头等新命令与配置的实战用法。

版本总览

Modern.js 7~8 月的最新版本为v1.17.0，本双月的主要更新集中在四个方向：

• 支持 React 18：完成框架和插件对 React 18 的适配；
• 包版本统一：Modern.js 所有组成包的版本号进行统一，并提供升级命令；
• Modern.js Module 支持 bundle 构建：Module 项目支持对产物做 bundle 构建；
• Reduck v1.1：发布 Reduck v1.1，使用文档全面更新。

以下各节将逐一展开，并结合仓库源码说明其底层实现。

支持 React 18

Modern.js 框架和相关插件完成对 React 18 的适配。现在，只需要将项目中的react、react-dom两个包的版本升级到最新的 React 18 大版本，就可以使用 React 18 的新功能。

从当前仓库的运行时实现看，React 18 的适配深入到浏览器端渲染的底层：packages/runtime/plugin-runtime/CHANGELOG.md记录了「浏览器运行时移除 React 17 支持，并改为静态引入react-dom/client」的重构，以及「移动解析 window ssr data 到createRoot方法」的调整。也就是说，React 18 标志性的createRoot并发渲染入口已内建到 Modern.js 的运行时中，react-dom/client的静态引入保证了createRoot(...).render(...)这一新 API 在框架生成代码中的稳定可用。

需要特别注意的是：

• 使用@modern-js/create命令默认创建的项目，安装的依赖react、react-dom版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本；
• SSR 流式渲染功能在当时尚在开发中，暂不支持。

也就是说，v1.17.0 的 React 18 支持主要体现在客户端渲染与常规 SSR 场景，流式 SSR 需要等待后续版本。

Modern.js 包版本统一与升级工具

在此之前，组成 Modern.js 的各个包的版本号并不统一，Modern.js 自身的版本和这些包的版本缺少明确的对应关系。这不仅增加了官方维护成本，也给用户的使用和升级带来了很多困扰。

从v1.15.0版本开始，Modern.js 自身的版本号和所有组成包的版本号进行了统一：Modern.js v1.15.0 意味着所有组成包的版本号也是 v1.15.0。每次发布新版本，Modern.js 所有包都会使用统一的版本号执行发布，GitHub 仓库的 tag 编号与所有组成包的版本号一一对应。这种「单一版本号」策略让用户在升级时可以确信：升级主框架版本即等同于升级其依赖的全部组成包，无需再逐一核对各包的版本兼容矩阵。

使用 @modern-js/upgrade 自动升级

官方提供了专门的升级工具@modern-js/upgrade，可以自动升级 Modern.js 到当前的最新版本。使用方式为，在项目根路径下执行：

npx @modern-js/upgrade

从命令注册层面看，upgrade被纳入 Modern.js CLI 的一等命令集合：packages/solutions/app-tools/src/run/index.ts中的SUPPORT_CONFIG_PARAM_COMMANDS列表同时包含dev、build、start、serve、inspect、info与upgrade，意味着upgrade命令同样支持通过--config/-c参数指定配置文件来运行，行为与其余框架命令保持一致。

Modern.js Module 支持 bundle 构建

Modern.js Module 对底层实现进行重构，新增output.buildConfig配置，用于提供更加丰富的构建功能。

新的 Modern.js Module 项目，不仅支持对产物做bundless 构建，也支持bundle 构建。通过配置buildConfig下的buildType，即可进行 bundle 构建：

import { defineConfig } from '@modern-js/module-tools'; export default defineConfig({ output: { buildConfig: { buildType: 'bundle', // 采用 bundle 构建 }, }, });

buildConfig 的定制能力

buildConfig下还支持bundleOptions配置，可以对构建行为做更多的自定义，例如：

• 设置产物文件名：定制 bundle 产物的输出命名规则；
• 是否进行代码分片：控制是否将公共依赖拆分为独立 chunk；
• 设置代码压缩方式：选择产物压缩工具与压缩级别。

对库开发者而言，这一组合意味着同一个 Module 项目既能以 bundless 方式产出供源码级联调的多文件产物，也能一键切换到 bundle 模式产出单文件、经过压缩的发布包，从而兼顾「开发调试友好」与「发布体积可控」两种诉求。buildType: 'bundle'与bundleOptions搭配使用，即可在保持项目结构不变的前提下按需调整产物体积与形态。

Reduck v1.1

Reduck 作为 Modern.js 的第一方状态管理方案，发布 v1.1 版本，增加对React 18 Concurrent Rendering的支持，并对开发体验和功能稳定性做了大量优化。

新增 API

• useStore：可以在组件内获取当前组件树共享的 Store，满足在组件外访问 Model 的场景需求；
• handleEffect：一个工具函数，可以极大地简化异步数据获取的逻辑代码；
• connect：HOC 风格的 API，用于访问 Model。

开发体验优化

Reduck 优化了组成包的组织结构，减少用户侧依赖数量：

• 现在只需要引入@modern-js-reduck/react一个包；在 Modern.js 中 Reduck 功能已内置，无需手动引入包；
• 优化 API 的 TypeScript 类型定义，改进类型信息的自动推导，整体达到TS 支持开箱即用。

此外，Reduck 的使用文档与 API 文档都做了全面更新，提供了更加丰富和详尽的内容。对于从 React 17 迁移到 React 18 的项目，Reduck v1.1 对 Concurrent Rendering 的支持让状态更新可以更好地配合 React 18 的并发调度特性，避免在并发模式下出现状态读取时序问题。

其他更新

命令和配置

新增命令：

• upgrade：自动升级 Modern.js 版本，功能同执行npx @modern-js/upgrade命令；
• inspect：通过该命令可以输出当前项目使用的完整 rspack 配置。从源码实现看（packages/solutions/app-tools/src/commands/inspect.ts），该命令首先获取已初始化的appContext.builder，然后调用builder.inspectConfig({ mode, verbose, outputPath, writeToDisk: true })，并将归一化后的完整 Modern.js 配置以extraConfigs形式一并输出——也就是说，inspect不仅能查看底层 rspack 配置，还能同时看到框架最终生效的完整配置对象，非常适合排查配置合并问题；
• gen-release-note：自动根据当前仓库的 changesets 信息生成发布日志。官方同时提供了包版本管理专题文档，帮助开发者认识和使用 changesets 及相关功能。

新增配置：

• source.preEntry：用于配置全局脚本，这段脚本会早于页面的代码执行。

在类型层面（packages/solutions/app-tools/src/types/config/source.ts），preEntry的类型为string | string[]，默认值为[]，注释明确说明其作用是在每个页面入口之前加入代码、先于页面代码执行，可用于注入 polyfill、设置全局样式等。

在实现层面（packages/runtime/plugin-runtime/src/cli/code.ts），框架会通过normalizePreEntry将配置统一归一化为字符串数组，再通过resolvePreEntryImportPath把相对路径解析为绝对路径；若路径位于src目录内，还会优先转换为内部src别名以保持导入简短稳定。最终在生成入口文件index.jsx时，将import '...'语句注入到真实入口代码之前，从而保证 preEntry 脚本一定先于页面逻辑执行。该文档的详细说明见 pre-entry.mdx。

BFF

• 新增afterLambdaRegistedhook：用于使用 Express 框架时，在 BFF 函数注册路由之后执行。可用来添加错误处理逻辑、新增路由等；
• 优化使用 Express 框架开发场景下的热更新性能。在比较大的项目中，BFF 函数更改，热更新也可以在几十毫秒内完成。

SSR

• SSR 产物添加 Sourcemap：优化服务端调试 SSR 代码的体验。启用后，服务端渲染代码出现异常时可以直接映射回 TypeScript/JSX 源码定位问题，而不再面对压缩混淆后的产物堆栈。

Web Server

• 支持按入口设置响应头。在 server.routes 中，通过配置入口的resHeaders即可为指定页面入口定制响应头，例如：

export default defineConfig({ server: { routes: { 'page-a': { route: ['/a', '/b'], resHeaders: { 'x-modern-test': '1', }, }, }, }, });

该配置在生产与开发环境均生效，也可以根据NODE_ENV区分环境设置不同的响应头；若只需要在开发环境设置响应头，官方建议改用tools.devServer.headers。

小结

v1.17.0 作为 2022 年 7~8 月的双月版本，为 Modern.js 的后续演进奠定了三个关键基础：React 18 的运行时适配（以静态引入react-dom/client与createRoot重构为标志）、统一版本号的发布与升级体系（@modern-js/upgrade一键升级）、以及Module 工具链的 bundle 构建能力（output.buildConfig/buildType/bundleOptions）。配合inspect、gen-release-note、source.preEntry、afterLambdaRegisted、按入口响应头等新命令与配置，这一版本同时改善了框架自身的可维护性和终端用户的应用开发、调试与发布体验。

• 前端
• 后端
• Web框架