Modern.js 项目构建问题排查指南

前言

Modern.js 是一个现代化的前端开发框架，它基于 Rsbuild 构建工具封装了自己的构建系统。在实际开发过程中，开发者可能会遇到各种构建相关的问题。本文将系统性地梳理 Modern.js 项目中常见的构建问题及其解决方案，帮助开发者快速定位和解决问题。

基础排查方法

1. 检查 Rsbuild 相关文档

Modern.js 内部基于 Rsbuild 构建工具，因此许多构建问题可以直接参考 Rsbuild 的官方 FAQ：

• 功能相关问题
• 异常错误问题
• 热更新(HMR)问题

2. 清除构建缓存

当遇到奇怪的构建问题时，清除缓存往往是第一步：

rm -rf ./node_modules/.cache

Modern.js 默认将 webpack 缓存生成在 ./node_modules/.cache/webpack 目录下。

常见问题及解决方案

1. webpack 编译参数错误

错误现象：

TypeError: The 'compilation' argument must be an instance of Compilation

原因分析： 这通常是由于项目中安装了错误版本的 webpack 或多个 webpack 版本冲突导致的。

解决方案：

1. 避免在项目中直接声明 webpack 依赖
2. 统一项目中各依赖的 webpack 版本
3. 尝试删除 lock 文件后重新安装依赖

2. Monorepo 中模块引用失败

错误现象：

You may need an additional loader to handle the result of these loaders.

原因分析： Modern.js 默认不会编译 node_modules 或当前项目目录外的文件。

解决方案：

1. 启用源码构建模式
2. 配置 source.include 指定需要额外编译的目录
3. 预构建依赖的子项目

3. 运行时 exports is not defined 错误

原因分析： CommonJS 模块被 Babel 编译导致。

解决方案：

1. 避免将 CommonJS 模块加入 Babel 编译
2. 设置 Babel 的 sourceType 为 unambiguous

export default {
  tools: {
    babel(config) {
      config.sourceType = 'unambiguous';
    },
  },
};

4. 编译进度条卡住无报错

排查步骤：

1. 检查 Babel 配置是否正确
   • 插件/预设名称是否正确
   • babel-plugin-import 配置是否正确
2. 检查是否在编译大型 JS 文件
   • 可禁用 babel-plugin-styled-components

export default {
  tools: {
    styledComponents: false,
  },
};

5. webpack 缓存失效

排查方法： 添加调试配置查看缓存失效原因：

export default {
  tools: {
    webpack(config) {
      config.infrastructureLogging = {
        ...config.infrastructureLogging,
        debug: /webpack\.cache/,
      };
    },
  },
};

6. 引用 lodash 类型报错

错误现象：

The lodash method `DebouncedFunc` is not a known module.

解决方案： 使用 import type 明确导入类型：

import { debounce } from 'lodash';
import type { DebouncedFunc } from 'lodash';

高级调试技巧

查看最终 webpack/Rspack 配置

Modern.js 提供了 inspect 命令来查看最终生成的配置：

npx modern inspect

该命令会输出：

• Builder 配置
• Rspack 配置(web)

总结

本文梳理了 Modern.js 项目中最常见的构建问题及其解决方案。遇到构建问题时，建议按照以下步骤排查：

1. 清除缓存尝试
2. 检查是否有明显的配置错误
3. 使用 inspect 命令查看最终配置
4. 根据具体错误信息参考本文对应解决方案

通过系统性地理解和解决这些问题，开发者可以更高效地使用 Modern.js 进行项目开发。