UmiJS 4中子应用配置qiankun.slave后的资源路径问题解析

在使用UmiJS 4框架开发微前端应用时，很多开发者会遇到一个典型问题：当子应用配置了qiankun.slave后，本地开发环境运行正常，但在构建后通过preview命令预览时，会出现umi.js等资源文件404的错误。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象

开发者配置了qiankun.slave = {}后，在本地开发环境下应用运行正常。但当执行max build构建后，使用max preview命令预览时，浏览器控制台会报错，提示无法加载umi.js等资源文件。具体表现为：

• 访问http://localhost:4172/umi.js返回404
• 但访问http://localhost:4172/[项目名称]/umi.js却能正常加载

问题根源分析

这个问题源于UmiJS 4与qiankun微前端框架的默认行为交互：

1. qiankun.slave的默认行为：当配置qiankun.slave后，UmiJS会自动将应用的base路径修改为package.json中的name字段值。这是为了在微前端场景下区分不同子应用。

2. preview命令的特殊性：UmiJS的preview命令主要用于本地临时验证构建结果，其设计相对简单。在preview模式下，资源文件默认会在base路径下提供。

3. 路径不匹配：由于qiankun修改了base路径，但preview服务仍期望在根路径下提供资源，导致路径不匹配而出现404错误。

解决方案

针对这一问题，开发者可以根据实际需求选择以下解决方案：

方案一：禁用qiankun的base修改

如果您的应用不需要作为子应用独立运行，可以禁用qiankun对base路径的修改：

// .umirc.ts
export default {
  qiankun: {
    slave: {
      shouldNotModifyDefaultBase: true,
      shouldNotModifyRuntimePublicPath: true
    }
  }
}

这两个配置项分别控制：

• shouldNotModifyDefaultBase：禁止修改默认base路径
• shouldNotModifyRuntimePublicPath：禁止修改运行时publicPath

方案二：调整nginx配置

对于生产环境部署，如果确实需要保持子应用的独立性，可以调整nginx配置，确保资源请求路径与base路径一致：

location /your-app-name/ {
  alias /path/to/your/app/;
  try_files $uri $uri/ /your-app-name/index.html;
}

方案三：自定义publicPath

在UmiJS配置中显式指定publicPath，确保资源加载路径正确：

// .umirc.ts
export default {
  publicPath: process.env.NODE_ENV === 'production' ? '/your-app-name/' : '/'
}

最佳实践建议

1. 开发与生产环境区分：建议在开发环境保持默认配置，在生产环境根据实际部署需求调整配置。

2. 慎用preview命令：preview命令主要用于简单验证，对于复杂的微前端场景，建议搭建完整的本地测试环境。

3. 统一路径策略：确保base路径、publicPath和实际部署路径三者一致，避免路径混乱。

4. 渐进式配置：从简单配置开始，逐步添加qiankun相关配置，每步都验证功能是否正常。

通过理解UmiJS和qiankun的交互机制，开发者可以更好地掌控微前端应用的资源加载行为，避免类似问题的发生。在实际项目中，应根据具体场景选择合适的配置方案。