modulepreload:专为ES模块设计的预加载机制
先明确一个核心概念:modulepreload 是专门服务于 ES 模块的预加载机制。它的工作模式是“只下载,不执行”,并且需要你提供模块的绝对路径。关键点在于,它的 href 必须与后续 script 标签的 src 完全一致,跨域时务必加上 crossorigin 属性。更重要的是,它不会自动递归加载模块内部的子依赖,所有关键依赖都需要你手动声明。

简单来说,modulepreload 是一种前置的资源调度策略。它并非用来替代 defer 或 async,而是为了更早地启动关键模块文件的网络请求。用对了,能为首屏JS加载节省100到300毫秒的宝贵时间;可一旦写错,它就会静默失效——控制台连个错误提示都不会给,让人无从排查。
怎么写一个有效的 modulepreload 标签
基础写法看起来很简单:。但在实际项目中,有几个硬性条件必须遵守,否则标签就等于白写了:
- 路径必须“绝对”:
href得是绝对路径或根相对路径(比如/assets/main.mjs)。如果写成./main.mjs或../lib/utils.mjs这类相对路径,浏览器会直接忽略它。 - 字符串必须“完全匹配”:这个
href的值,必须和后面里的src一字不差。连查询参数(比如?v=2.1.0)都不能有出入,否则浏览器会认为这是两个不同的资源。 - 跨域必须加“通行证”:如果模块放在CDN或其他域名下(例如
https://cdn.example.com/app.mjs),那么标签上必须加上crossorigin属性。少了这个,预加载请求就会被浏览器悄悄跳过。 - 只认“模块”:这个机制专为ES模块设计。如果你试图用它去加载一个普通的、
type="text/ja vascript"的非模块脚本,它会静默失败,既不报错,也不会发起网络请求。
modulepreload 不会自动加载 import 的子模块
这是一个非常关键的认知点。你写了 ,假设 main.mjs 里面有一行 import { helper } from './helper.mjs',浏览器不会自动把 helper.mjs 也预加载下来。
- 依赖必须手动声明:所有你希望提前加载的关键子模块,都需要额外的手动声明。比如,你需要再加一行:
。 - 顺序有讲究:当有多个
modulepreload标签时,建议按照模块的执行依赖顺序来排列(例如先 vendor 库,再 main 主模块)。部分浏览器会依照这个顺序发起请求,这有利于TCP连接的复用,提升效率。 - 交给工具更靠谱:手动维护这份依赖列表,在真实项目中极易出现遗漏、错误或过期。因此,更明智的做法是交给构建工具自动化处理:Vite 默认就通过
build.rollupOptions.output.manualChunks及相关插件来生成完整的依赖链;Webpack 用户可以配置webpack-preload-plugin;Rollup 则需要配合rollup-plugin-module-preload这样的插件。
常见错误现象和验证方式
明明写了 modulepreload 却没看到效果,或者控制台报出 Failed to load module script 的错误?大概率是踩了下面几个坑:
“前端免费学习笔记(深入)”;
- 路径不一致:打开开发者工具的 Network 面板,仔细核对
main.mjs实际请求的完整URL,是否与link标签中的href完全一致(包括协议、端口、大小写、查询参数)。 - 缺少
crossorigin:对于跨域模块,如果link标签忘了加crossorigin属性,在 Network 面板里你根本看不到预加载请求,控制台也不会有任何提示,失效得悄无声息。 - 模块自身执行错误:模块本身存在语法错误,或者内部的
import路径写错了,这其实与modulepreload无关,但很容易被误判为预加载失败。 - 如何验证生效:打开 Chrome DevTools,进入 Network 面板,在筛选器(Filter)中输入你的模块名(如
main.mjs)。然后查看该请求的“Initiator”列,如果显示为preload,并且“Priority”列为Highest,那就说明预加载真正起作用了。
最后,必须警惕一个最容易被忽略的要点:预加载仅仅完成了“将文件字节拉取到浏览器缓存”这一步,它并不保证模块已经解析和执行完毕。如果你在 DOMContentLoaded 事件中立即调用模块导出的函数,仍然可能因为模块尚未执行而得到 undefined 错误——模块的执行时机,依然由页面中 标签的解析位置决定,modulepreload 不会改变这个根本规则。
