Umi.js 项目中脚本加载顺序的优化实践

2025-05-14 23:53:34作者：郦嵘贵Just

问题背景

在使用 Umi.js 构建前端项目时，开发者经常会遇到需要引入第三方脚本的情况。一个常见的问题是：当通过配置项 scripts 引入外部脚本（如 axios.min.js）时，构建后的产物中这些脚本会被放置在 umi.js 之后，导致运行时出现变量未定义的错误。

问题分析

这个问题源于 Umi.js 默认的脚本加载机制。在开发模式下，一切运行正常，但在生产构建后，脚本的加载顺序发生了变化。具体表现为：

使用 scripts 配置引入的脚本会被放置在 umi.js 之后
如果这些脚本中定义了全局变量，而 umi.js 中的代码又依赖这些变量，就会导致运行时错误
开发模式正常是因为开发服务器可能有不同的脚本加载策略

解决方案

方案一：使用 headScripts 配置

最直接的解决方案是使用 headScripts 替代 scripts 配置。headScripts 会将脚本放置在 HTML 的 <head> 部分，确保它们在 umi.js 之前加载。

// .umirc.ts 或 config/config.ts
export default {
  headScripts: ['/axios.min.js'],
  externals: {
    axios: 'axios',
  },
  esbuildMinifyIIFE: true,
}

优点：

配置简单直接
确保脚本在 umi.js 之前加载

缺点：

脚本会阻塞 HTML 渲染
可能影响页面加载性能

方案二：自定义 HTML 修改插件

对于需要更精细控制脚本位置的情况，可以创建自定义插件来修改 HTML 结构：

创建插件文件 plugins/modify-html.ts

export default (api: IApi) => {
  api.modifyHTML($ => {
    // 获取所有 script 标签
    const scripts = $('script').toArray()
    // 找到 umi.js 脚本
    const umiScript = scripts.find(el => $(el).attr('src')?.includes('umi.'))
    // 其他脚本
    const otherScripts = scripts.filter(el => el !== umiScript)
    
    // 移除所有 script 标签
    $('script').remove()
    
    // 先添加其他脚本
    otherScripts.forEach(el => $('body').append(el))
    
    // 最后添加 umi.js
    if (umiScript) $('body').append(umiScript)
    
    // 可选：HTML 压缩优化
    let html = $('html').html() ?? ''
    html = html
      .split('\n')
      .map(line => line.trim())
      .filter(line => line.length > 0)
      .join('')
      .replace(/>\s+</g, '><')
    $('html').html(html)
    
    return $
  })
}

在配置中启用插件

export default {
  plugins: ['./plugins/modify-html.ts'],
  // 其他配置...
}

优点：

完全控制脚本加载顺序
可以将脚本放在 <body> 中 umi.js 之前
不影响 HTML 初始渲染

缺点：

需要编写额外代码
增加了项目复杂度

最佳实践建议

优先考虑 externals 配置：对于像 axios 这样的库，最佳实践是通过 externals 配置外部依赖，而不是直接引入脚本。
评估脚本必要性：考虑是否真的需要引入完整脚本，也许可以通过 npm 包的形式引入。
性能考量：如果使用 headScripts，考虑添加 async 或 defer 属性来优化加载性能。
环境差异处理：注意开发环境和生产环境的差异，确保测试覆盖两种环境。

总结

在 Umi.js 项目中管理第三方脚本的加载顺序是一个常见但重要的问题。通过理解 Umi.js 的构建机制和提供的配置选项，开发者可以灵活地控制脚本加载行为，确保应用正常运行的同时兼顾性能优化。对于大多数情况，使用 headScripts 或 externals 配置就能解决问题；对于更复杂的需求，自定义 HTML 修改插件提供了强大的灵活性。

umi

A framework in react community ✨

项目地址：https://gitcode.com/GitHub_Trending/um/umi

登录后查看全文

Umi.js 项目中脚本加载顺序的优化实践

问题背景

问题分析

解决方案

方案一：使用 headScripts 配置

方案二：自定义 HTML 修改插件

最佳实践建议

总结

热门内容推荐

最新内容推荐

项目优选

Umi.js 项目中脚本加载顺序的优化实践

问题背景

问题分析

解决方案

方案一：使用 headScripts 配置

方案二：自定义 HTML 修改插件

最佳实践建议

总结

相关内容推荐

热门内容推荐

最新内容推荐

项目优选