UmiJS 4 中动态获取 publicPath 的解决方案

背景介绍

UmiJS 4 作为一款流行的前端框架，在升级过程中对模板系统进行了重构，移除了传统的 document.ejs 模板引擎。这一变化给开发者带来了一些适应上的挑战，特别是那些需要动态获取 publicPath 路径的场景。

问题本质

在 UmiJS 3 及之前版本中，开发者可以通过 <%= publicPath %> 语法在模板中直接插入配置的静态资源路径。但在 UmiJS 4 中，这一机制发生了变化，导致开发者需要寻找新的解决方案来获取实际的 publicPath 值，而不仅仅是配置中的静态值。

技术解决方案

UmiJS 4 提供了两种主要方式来处理 publicPath 的动态获取需求：

1. 直接配置方式

最简单的方式是在配置文件中直接设置 publicPath：

// .umirc.ts 或 config/config.ts
export default {
  publicPath: process.env.NODE_ENV === 'production' ? '/prod-path/' : '/dev-path/'
}

这种方式适用于大多数静态环境配置的场景。

2. 动态运行时方案

对于需要更灵活控制的场景，UmiJS 4 提供了运行时动态设置的能力：

// .umirc.ts 或 config/config.ts
export default {
  runtimePublicPath: true,
  headScripts: [
    `window.publicPath = '自定义路径或动态计算逻辑';`
  ]
}

这种方案的优势在于：

• 可以在运行时动态计算 publicPath
• 适用于微前端等需要动态调整资源路径的场景
• 保持了配置的灵活性

实现原理

当启用 runtimePublicPath 选项时，UmiJS 会在构建过程中：

1. 将所有资源引用路径改为相对路径
2. 在 HTML 头部注入设置的 headScripts
3. 运行时通过 JavaScript 动态控制资源加载路径

这种方式避免了传统模板引擎的硬编码问题，提供了更大的灵活性。

最佳实践建议

1. 简单项目：直接使用环境变量区分配置即可

2. 复杂项目：考虑使用运行时方案，特别是：

   • 需要支持多环境部署
   • 作为微应用集成到其他系统中
   • 需要动态计算资源路径的场景

3. 调试技巧：构建后检查生成的 HTML 文件，确认 publicPath 设置是否符合预期

总结

UmiJS 4 通过取消传统模板引擎，推动了更现代化的配置方式。对于 publicPath 的需求，开发者现在有更灵活的选择，既可以直接配置，也可以通过运行时 JavaScript 动态控制。理解这些机制有助于开发者更好地适应 UmiJS 4 的变化，构建更健壮的前端应用。