前两年把一个小项目从「几个 script 标签按顺序引」改成 ES 模块,改完页面白屏,控制台一行红字:
Uncaught SyntaxError: Unexpected token 'export'
代码本身没写错,问题出在 <script src="./main.js"></script> 少了一个属性。浏览器默认把脚本当普通脚本执行,不认识 export 这种模块语法;要写成 <script type="module" src="./main.js"></script>,它才会按模块规则解析。
这类问题在切模块化时很常见:路径要不要写扩展名、为什么 file:// 打开报跨域、为什么同一个模块只执行一次、为什么两个文件互相引用时拿到 undefined。这篇把这些一次讲清。
这篇讲什么:模块化解决的是什么问题、ESM 的 import/export 怎么写、默认导出和具名导出怎么选、模块的作用域和加载规则、循环依赖到底怎么回事。读完你能做到:把一个散落的脚本拆成模块;写出不容易出错的导出结构;遇到「模块加载失败」「拿到 undefined」能快速定位原因。
没有模块之前,问题出在哪
早期页面靠多个 <script> 按顺序加载,所有文件共享同一个全局作用域。看着简单,实际有三个绕不开的问题:
命名冲突
两个文件都定义了 format,后加载的静默覆盖前一个。不报错,只是功能悄悄坏了,而且很难查是哪个文件覆盖的。
依赖靠顺序
工具函数必须写在业务脚本前面。文件一多,顺序成了隐形契约,谁加了一个文件忘了调整顺序,线上就报 xxx is not defined。
不知道谁用了谁
删一个「看起来没人用」的函数,可能有三处调用。没有显式声明依赖,只能全局搜索,靠人记。
模块化就是把每个文件变成独立作用域,文件之间用显式的 import 和 export 建立关系。谁依赖谁写在文件顶部,删改的时候一眼能看到影响范围。
更麻烦的是「看起来能用」。两个文件都声明 function format(),在普通脚本里,函数声明会挂到全局,后加载的直接覆盖前者,页面不报错,只是金额格式化从两位小数变成了一位。等有人发现数字不对,往往已经过去几天,而且在全局搜索 format 会搜到一堆同名函数。
那个年代常见的补丁是立即执行函数:把每个文件包进 (function () { ... })(),变量不再外泄。但它只解决了污染,没解决依赖声明和加载顺序,模块之间还是靠挂到 window 上的约定通信。
最基本的 import 和 export
一个文件里定义的东西,默认只有自己能用;想给别人用,就 export 出去。用的一方 import 进来。
// utils/format.js
export function formatPrice(cents) {
return "¥" + (cents / 100).toFixed(2);
}
export const TAX_RATE = 0.06;
// main.js
import { formatPrice, TAX_RATE } from "./utils/format.js";
console.log(formatPrice(1990)); // "¥19.90"
console.log(TAX_RATE); // 0.06
几个细节:浏览器里路径要写扩展名 .js,不能省;路径是相对当前文件还是以 / 开头,含义和普通 URL 一样;导入的名字必须和导出的名字一致,除非用 as 改名:
import { formatPrice as price } from "./utils/format.js";
console.log(price(1990)); // "¥19.90"
// 整体导入,适合导出很多、又不想一个个列的场景
import * as format from "./utils/format.js";
console.log(format.formatPrice(1990));
还有一种是「只为执行副作用」,比如注册全局样式、初始化埋点:
import "./styles/theme.css"; // 打包工具里常见,浏览器原生模块不认 CSS
import "./analytics.js"; // 只要执行,不需要里面的导出
导出不一定要写在声明前面,也可以先声明、最后统一列出:
function formatPrice(cents) { /* ... */ }
const TAX_RATE = 0.06;
export { formatPrice, TAX_RATE };
入口文件常用 export * from "./user.js" 把所有导出再抛出去。但两个模块有同名导出时,export * 会静默跳过冲突的名字,不报错;用 export * as userApi from "./user.js" 加命名空间更明确。桶文件堆多了,依赖图会变得很大,开发服务器启动和热更新都会变慢。
有两个行为容易让人意外。第一,import 会被提升到模块顶部,写在文件中间也一样先执行依赖;所以不能把 import 放进 if 里按条件加载,语法上直接不允许,条件加载只能用后面的动态 import()。
第二,导入的绑定是只读的。下面这行会报错:
import { TAX_RATE } from "./utils/format.js";
TAX_RATE = 0.13; // TypeError,导入的绑定不能重新赋值
但「只读」指的是绑定不能换,不是值永远不变。如果导出方是一个对象,导入方修改对象的属性,所有引用方都会看到,因为大家拿的是同一个对象。要防止这种意外,导出方可以 Object.freeze,但它只冻结第一层。
路径写法的区别也要清楚:./utils/format.js 是相对当前文件;/utils/format.js 是相对站点根目录;format 这种不带 ./ 的叫裸说明符,浏览器原生 ESM 不认识,必须配 import map 或交给打包工具。改目录时,相对路径跟着文件走,根路径不跟着走,这是移动文件后 404 的常见原因。
默认导出和具名导出,怎么选
导出有两种形式,功能上都能用,但习惯差别很大:
// 具名导出:可以有很多个,导入时必须用对应的名字
export function getUser() {}
export function saveUser() {}
// 默认导出:一个模块只有一个,导入时可以随便起名
export default function () {}
// 导入
import anything from "./user.js";
我的选择标准比较固定:工具函数、常量、类型,用具名导出;一个文件只提供一个主体(比如一个组件、一个类),可以用默认导出。
原因在维护上。具名导出导入时名字固定,全局搜索 getUser 能找到所有使用处;默认导出可以被改成任意名字,同一个函数在三个文件里叫三个名字,搜索就断了。另外具名导出对编辑器的自动导入、重命名更友好。
一个模块里不要同时用两种导出方式,尤其是「默认导出加一堆具名导出」。用的人会困惑:到底该 import 默认那个,还是花括号取具名的那个?团队里统一一种,比争论哪种更好重要。
重新导出(re-export)在入口文件里很常用,把散落的模块收成一个出口:
// api/index.js
export { getUser, saveUser } from "./user.js";
export { getOrder } from "./order.js";
export { default as request } from "./request.js";
// 使用方只需要认一个入口
import { getUser, getOrder } from "./api/index.js";
默认导出在语法上其实是名为 default 的具名导出,所以也能这样导入:
import { default as request } from "./request.js";
它最大的问题是名字由使用方决定。import request from "./request.js" 和 import http from "./request.js" 指的是同一个东西,但全局搜索 request 找不到第二处。具名导出没有这个问题,改名必须用 as,搜索原名还能找到。
默认导出对 tree-shaking 也不友好。打包工具更难判断默认导出的对象里哪些属性被用到,尤其是 export default { a, b, c } 这种写法,往往整个对象都被保留。具名导出可以精确到单个函数。
还有一个循环依赖相关的细节:如果两个模块互相引用,而其中一方用默认导出,拿到 undefined 的概率更高,因为默认导出的绑定初始化时机同样受执行顺序影响。结构上能拆就拆,别指望记住顺序。
模块只执行一次,所以它天然是单例
同一个模块被多个文件 import,不管写了几次,模块代码只执行一次,大家拿到的都是同一份导出。这一点经常被用来做「全局唯一的状态」:
// store.js
let token = null;
export function setToken(value) { token = value; }
export function getToken() { return token; }
// a.js 和 b.js 都 import 了 store.js
// 在 a.js 里 setToken("abc"),b.js 里 getToken() 也能拿到 "abc"
这不神秘,就是「模块只执行一次」的结果。反过来说,如果你在模块顶层写了有副作用的代码(发请求、读本地存储、改 DOM),它也只会在第一次被导入时执行一次,之后不会再跑。副作用放顶层要谨慎,别人 import 你的模块时,这些代码会「顺便」执行。
模块作用域还有一个好处:顶层声明的变量不会跑到 window 上。你写 const token = ...,别的文件不 import 就拿不到,不会污染全局。
「只执行一次」是按模块 URL 算的,不是按文件算。给同一个文件加不同的查询参数,浏览器会当成两个模块:
import { setToken } from "./store.js?v=1";
import { getToken } from "./store.js?v=2"; // 另一份实例,状态不共享
上线换缓存时给静态资源加版本号,很容易出现这种双实例:A 页面从旧地址拿 token,B 页面从新地址读,读不到。排查「明明登录了却拿不到状态」时,先看 Network 里同一个文件是不是加载了两次。
打包后也一样。依赖树里出现同一个库的两个版本,每个版本各有自己的模块实例,单例就不再唯一。用 npm ls 包名 看有没有重复版本,比在代码里加日志快。
另外,模块缓存是按运行环境分的。浏览器每个页面一份,iframe 各算各的;Node 里同一个进程共用模块缓存,所以模块顶层存的用户状态会在不同请求之间串。服务端用 ESM 写请求相关状态时,别放在模块顶层。
循环依赖:为什么会拿到 undefined
两个文件互相 import,就叫循环依赖。它不一定报错,但结果经常让人困惑:
// a.js
import { bValue } from "./b.js";
export var aValue = "A";
console.log("a 里看到的 bValue:", bValue);
// b.js
import { aValue } from "./a.js";
export const bValue = "B";
console.log("b 里看到的 aValue:", aValue);
// main.js
import "./a.js";
实际执行时,a.js 先开始执行,发现要 b.js,转去执行 b.js;b.js 又要 a.js,但 a.js 已经在执行中,不会重来,直接把「当前已经准备好的导出」给它。这里的 aValue 用 var 声明,模块初始化阶段就被置为 undefined,所以 b 里打印的是 undefined;等 b 执行完,回到 a,a 继续往下执行把 aValue 赋成 "A",而 bValue 已经就绪,所以 a 里能打印 "B"。
如果把 var 换成 const 或 let,现象会变成直接报错 ReferenceError: Cannot access 'aValue' before initialization,因为这两个声明的绑定在初始化前处于暂时性死区,读一下都不行。用 function 声明则相反,函数在模块实例化阶段就创建好了,循环依赖里通常能直接调用,这也是老代码里函数声明多、出问题时反而少的原因。
这就是循环依赖的典型现象:谁先执行,谁就可能拿到对方的 undefined。它不是 bug,是加载顺序决定的。
处理办法按优先级:
| 做法 | 说明 | 适用场景 |
|---|---|---|
| 拆出公共模块 | 两个文件都依赖的常量或函数,挪到第三个文件 | 最推荐,从结构上消除循环 |
| 延迟到函数内部 import | 用动态 import(),真正调用时才加载 | 确实需要在运行时才确定依赖 |
| 延迟读取 | 不在模块顶层使用对方的值,等函数执行时再读 | 临时绕开,结构没真正解决 |
undefined。遇到这种怪现象,先看两个文件是不是互相 import。动态 import:需要时才加载
import() 是函数形式,返回 Promise,可以用在条件分支和函数里:
button.addEventListener("click", async () => {
const { openChart } = await import("./chart.js");
openChart(data); // 只有点了按钮才会下载并执行 chart.js
});
// 按环境加载不同实现
const api = await import(
isMock ? "./api-mock.js" : "./api-real.js"
);
静态 import 会在模块执行前就加载所有依赖,动态 import() 是真正用到才加载。做首屏优化、按路由拆包、按条件加载大模块时用它。代价是加载时机变成运行时的,依赖关系不再是一眼可见,别为了「按需」把简单的引用都改成动态。
动态导入有几个实际细节。返回的 Promise 解析出来的是模块命名空间对象,解构时名字要和导出一致;同一个路径重复 import() 不会重复下载和执行,模块缓存照样生效;多个动态导入可以 Promise.all 并行,别在循环里一个个 await,那会变成串行。
路径如果是变量拼接,打包工具无法静态分析,可能把整个目录都打进去,也可能在运行时 404。常见的按路由加载写成 import(`./pages/${name}.js`),要确认构建配置能覆盖到这些文件。
动态导入失败要处理。网络断开、CDN 路径变了、版本更新后旧文件被删,都会让 import() reject。首屏关键路径上的动态导入,至少给用户一个「加载失败,点击重试」的出口,不要让按钮点了没反应。
在浏览器里用模块,几个必须知道的限制
如果项目没有打包工具,直接把 ESM 丢给浏览器跑,会碰到几条规则:
| 规则 | 现象 | 怎么处理 |
|---|---|---|
必须声明 type="module" | 报 Unexpected token 'export' | 给入口 script 加上这个属性 |
| 路径要写完整扩展名 | 报 404,文件名找不到 | 写 ./utils/format.js,别省 .js |
不能从 file:// 加载 | 报跨域或 CORS 相关错误 | 起一个本地静态服务,用 http 访问 |
| 模块默认是严格模式 | 裸调函数的 this 变成 undefined | 这是预期行为,改代码而不是关严格模式 |
| 模块是延迟执行的 | 等价于带了 defer,DOM 解析完才跑 | 不用再手动加 defer |
还有一点容易忽略:模块脚本里的顶层 await 是合法的(顶层 await),普通脚本不行。这个特性有用,但会让模块的执行时机更晚,排查加载顺序时容易看漏。
MIME 类型是另一个高频坑。模块脚本必须以 JavaScript 的 MIME 返回,服务器如果对不存在的路径回退到 index.html,浏览器会报 Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"。看到这个别怀疑代码,先去 Network 看那个请求返回的到底是不是 HTML。
跨域加载模块还要求 CORS。普通脚本可以跨域引用,模块脚本默认按 CORS 规则走,CDN 没配 Access-Control-Allow-Origin 就会失败;需要时给 script 加 crossorigin 属性,同时确认 CDN 响应头。
原生 ESM 不支持裸说明符,import React from "react" 在浏览器里会报 Failed to resolve module specifier "react"。要么写完整相对路径,要么用 import map 把裸名映射到具体 URL。import map 必须在任何模块脚本之前出现,而且各浏览器的支持情况要先确认。
和 CommonJS 的区别,别混着写
Node 早期用的是 CommonJS,语法是 require 和 module.exports。两套东西长得像,机制不同:
| 对比项 | ESM | CommonJS |
|---|---|---|
| 语法 | import / export | require / module.exports |
| 加载时机 | 静态分析,先加载依赖再执行 | 运行时同步读取 |
| 导入的绑定 | 实时绑定,原模块改变量值,导入方能看到 | 拿到的是值的拷贝 |
| 顶层 await | 支持 | 不支持 |
浏览器原生只认 ESM,require 在浏览器里没有定义,除非你用打包工具。所以看到「浏览器里 require is not defined」,不是浏览器坏了,是用错了模块体系。
require,要靠 createRequire。新项目直接用 ESM,少折腾。「实时绑定」和「值拷贝」不是术语游戏,会直接改变结果。ESM 里导出的变量被重新赋值,导入方能看见新值:
// counter.js
export let count = 0;
export function inc() { count += 1; }
// main.js
import { count, inc } from "./counter.js";
inc();
console.log(count); // 1
CommonJS 里同样的写法,导入方拿到的是当时那个值的拷贝:
// counter.cjs
let count = 0;
module.exports = { count, inc() { count += 1; } };
// main.cjs
const m = require("./counter.cjs");
m.inc();
console.log(m.count); // 0,拷贝没有跟着变
这也是为什么把 CJS 迁到 ESM 时,有些「读不到最新值」的代码突然就好了。反过来说,依赖 ESM 的实时绑定写跨模块状态,会让数据流更难追,能通过函数传参就别共享可变变量。
Node 里还有几个差异:ESM 没有 require、module、__dirname,要拿当前文件路径用 import.meta.url;.mjs 固定按 ESM 解析,.cjs 固定按 CJS;package.json 里的 "type": "module" 会让 .js 默认按 ESM 处理。
完整场景走查:活动页从全局脚本拆成模块
需求是一个商品活动页:展示 200 个商品、格式化价格、上报曝光埋点;点「查看走势」时才需要加载一个 180KB 的图表库。原来所有代码塞在三个 <script> 里,靠顺序保证能用。现在要拆成模块,顺便把图表改成按需加载。
第一版拆了四个文件:api.js 负责请求,format.js 负责价格,track.js 负责埋点,main.js 负责渲染。HTML 还是老写法:
<script src="./js/main.js"></script>
本地打开,页面直接白屏,控制台第一行:
Uncaught SyntaxError: Unexpected token 'export'
原因是浏览器把 main.js 当普通脚本解析,不认识 export。加上 type="module" 后,又冒出新错误:
Failed to load module script: Expected a JavaScript module script
but the server responded with a MIME type of "text/html"
这次是 import { formatPrice } from "./format" 少写了 .js。开发服务器找不到文件,回退返回了首页 HTML,浏览器按模块去解析 HTML,自然报 MIME 不对。补上扩展名,页面终于出来。
到这一步,本地这版能跑:商品列表、价格、埋点都正常,团队就按这个结构提测了。上预发后,问题一个接一个。
首先,商品列表加载失败。查 Network,请求路径是 /api/products,而接口实际在 /activity/2026-11/api/products。第一版把接口地址写成了根路径,本地开发服务器在根目录,碰巧对;部署到子路径就错了。改法是把环境相关的地址收进一个 config.js,其他模块只 import 它,部署时改一处。
// config.js
export const API_BASE = "/activity/2026-11/api";
// api.js
import { API_BASE } from "./config.js";
export async function fetchProducts() {
const res = await fetch(`${API_BASE}/products?limit=200`);
if (!res.ok) throw new Error(`商品接口失败:${res.status}`);
return res.json();
}
埋点又出问题。页面能渲染,但曝光事件的 userId 一直是 undefined。两个文件互相引用:track.js 为了拿用户信息 import 了 api.js,api.js 为了记录请求日志 import 了 track.js。入口先执行 api.js,它转去执行 track.js;track.js 顶层的初始化代码这时去读 api.js 里的用户变量,而那个绑定还没初始化,结果就是空值或直接抛 ReferenceError。无论哪一种,埋点里的 userId 都不对。
修法不是调整 import 顺序,而是把共用的用户信息拆到第三个模块 session.js,两边都依赖它,循环断掉:
// session.js
let userId = null;
export function setUserId(id) { userId = id; }
export function getUserId() { return userId; }
// track.js
import { getUserId } from "./session.js";
export function track(event, payload) {
navigator.sendBeacon("/activity/2026-11/api/track", JSON.stringify({
event, userId: getUserId(), ...payload
}));
}
最后是图表。第一版在 main.js 顶部直接 import { openChart } from "./chart.js",导致首屏必须等 180KB 的图表代码下载完。改成点击时再加载,首屏少了一个大请求;按钮第一次点击会多等两三百毫秒,可以在鼠标移上去时预加载。
const chartButton = document.querySelector("#show-trend");
chartButton.addEventListener("click", async () => {
chartButton.disabled = true;
try {
const { openChart } = await import("./chart.js");
openChart(await fetchProducts());
} catch (err) {
chartButton.textContent = "图表加载失败,点击重试";
console.error(err);
} finally {
chartButton.disabled = false;
}
});
这一圈走完,页面能上线了:入口是一个 type="module" 的脚本,所有路径带扩展名,接口地址集中在一个配置模块,循环依赖拆开,图表按需加载。每一步都不是「模块语法」的问题,而是模块化把原来藏在顺序和全局里的隐式约定,变成了必须显式写出来的东西。
错误现象对照
下面这些报错在切模块、调路径、上线部署时都很常见。先看现象,再对原因,最后按第三列去查。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
Uncaught SyntaxError: Unexpected token 'export' | 入口脚本没写 type="module",被当成普通脚本解析 | 看 HTML 里那个 script 标签的属性 |
Failed to load module script: ... MIME type of "text/html" | 路径写错、少扩展名,服务器回退返回了 HTML | Network 里看该请求的响应内容是不是首页 |
Failed to resolve module specifier "react" | 浏览器原生 ESM 不支持裸模块名,也没有 import map | 看 import 路径是否以 ./ 或 / 开头 |
Access to script at 'file:///...' from origin 'null' has been blocked by CORS policy | 用 file:// 直接打开页面加载模块 | 换成本地 http 服务再访问 |
某个模块拿到 undefined,或报 Cannot access 'x' before initialization | 循环依赖,且在模块顶层立即使用了对方的绑定 | 看两个文件是否互相 import,顶层是否有立即取值 |
| 改了代码刷新没变化,或出现两个单例 | 同一文件带了不同查询参数,或部署了两份副本 | 查 Network 里模块 URL 是否一致 |
边界与代价
模块化不是文件越碎越好。一个 80 行的工具文件,为了「单一职责」拆成五个模块,每个都 import 两三个,最后依赖图比代码还长。判断标准:这个文件是否会被别处复用、是否有独立的状态或副作用、改动时是否需要单独测试。三个都否,就留在原处。
原生 ESM 直接上线也有边界。每个模块是一次网络请求,HTTP/2 下开销小一些,但 50 个模块在弱网下仍然比一个打包文件慢;没有打包就没有 tree-shaking、没有 TypeScript 和 JSX 转换、没有环境变量替换。小项目、内部工具可以直接用原生 ESM;面向公网、模块上百个的项目,还是需要构建步骤。
桶文件(barrel)要克制。一个 index.js 里 export * from 十几个模块,使用方一行 import 很爽,但构建工具会把整张依赖图拉进来,tree-shaking 变差,开发服务器热更新变慢,还容易制造循环依赖。公共入口保留少量稳定导出就够了,不要什么都往里塞。
服务端的边界更要注意。Node 里模块缓存跨请求共享,把用户相关状态放在模块顶层,A 用户的 token 会被 B 用户读到;这在本地单请求测试时完全看不出来。请求级状态要放在函数参数、请求对象或专门的上下文存储(比如 Node 的 AsyncLocalStorage)里,不要放模块变量。
动态导入的代价是延迟和不确定性。首屏关键功能不要动态加载;按需加载的文件在弱网下可能几百毫秒才到,交互要有加载态和失败重试。预加载能缓解,但别把所有可能用到的模块都预加载,那等于没拆。
循环依赖本身可以存在,很多成熟项目都有。它的边界是「不要在模块顶层立即使用对方的绑定」,以及「不要靠调整 import 顺序来修」。只要出现 undefined 或 ReferenceError,优先拆公共模块,而不是加注释说明顺序。
小结
undefined,也可能撞上暂时性死区直接报错;从结构上拆出公共模块是最干净的解法。这几件事今天就能自己搭个小页面验证:
- 建两个文件,一个导出、一个导入,先用普通
<script>打开,复现Unexpected token 'export',再加上type="module"。 - 把
import "./format"的扩展名去掉,用本地静态服务访问,观察 Network 里返回的是不是 HTML。 - 写一对互相 import 的模块,分别用
var和const导出,记录控制台是undefined还是ReferenceError。 - 给按钮加一个动态
import(),在 Network 面板确认点击前没有加载那个文件,点击后才出现请求。 - 让两个模块各
import同一个模块并打印日志,确认日志只出现一次。
下一篇讲Promise 与 async/await。模块解决「代码怎么分」,异步解决「等结果的时候怎么办」,两者在真实项目里几乎绑在一起:模块里的接口请求、按需加载,都是异步的。这篇里那个点击后才加载的图表,加载失败怎么重试、多个请求怎么并发,都要靠下一篇的工具来处理。