一个文件写到撑不住:模块 import/export 实战指南
一个 main.js 写到六百多行,菜单、点单、结算、打印全挤在一起。本文按 MDN 的 JavaScript modules、import 与 export 官方文档讲清楚:脚本与模块、具名与默认导出、as 改名、命名空间导入、barrel 总入口、副作用与 JSON 导入、提升与活绑定、动态 import、顶层 await 与 import.meta。

先把这篇的边界说清楚。站里已经有不少 JavaScript 基础指南:数组方法、解构赋值、Map 与 Set、Promise 与 async/await、try/catch、DOM 查询与遍历。这篇不讲它们,只讲一件事:一个文件写到撑不住的时候,怎么把它拆成模块,再用 import 和 export 把它们接起来。下面用到的“青石咖啡馆”还是那个虚构的练手项目:一个帮街边咖啡馆做点单的网页小工具。之前几篇讲的是它的点单页怎么写逻辑,这回讲的是它的代码本身:最早 main.js 一个文件写了六百多行,菜单、点单、结算、打印全挤在一起,改一处怕三处;这篇讲的就是怎么把它拆成 canvas.js、menu.js、order.js、checkout.js 几个模块,再由 main.js 接起来。本文所有以它为例的操作、代码和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于模块的语法和行为,都来自 MDN 的《JavaScript modules》《import》《export》三篇官方文档,来源见每篇的 meta 信息与 evidence 记录。文档里的例子,比如画方形、圆形、三角形的 canvas.js、square.js、circle.js,取质数的 getPrimes.js,取颜色的 getColors.js,都是文档自带的示例,不是真实服务。这篇不讲打包工具怎么写配置、不讲 CommonJS 的 require 怎么用,只讲浏览器里原生的 ES 模块。读完这篇,你应该能做到三件事:会拆、会接、会改名;知道默认导出和具名导出不是一回事;知道动态 import 和顶层 await 是什么时候用的。
第一步:脚本与模块是两种玩法,先分清再动手
拆模块之前,先要分清两种玩法:脚本和模块。MDN 在《JavaScript modules》开篇就讲了这个差别:JavaScript 代码可以用两种方式求值,一种是脚本,也就是传统脚本,另一种是模块。差别有两条。第一,解析的时候不一样:模块自动处在严格模式里,而且只有在模块里才能用 import 和 export 语句。第二,运行的时候不一样:模块在自己的作用域里执行,不在全局作用域里执行。也就是说,模块里声明的变量、函数、类,除非明确导出,否则外面看不见;想让外面的代码用,就得挂到全局对象上,比如浏览器里的 window,但那是下策。传统脚本正好反过来:挂到页面上的所有传统脚本都在同一个作用域里执行,也就是全局作用域,后面的脚本能直接用到前面脚本声明的变量。MDN 举的例子很直观:第一个脚本声明了 $ 函数,第二个脚本直接调 $.ajax,靠的就是大家都在全局作用域里。方便是方便,代价是规模一上来就乱:作用域污染和名字冲突成了大问题,jQuery 和 Underscore 这样的流行库把所有东西都收到 $ 和 _ 这样的特殊标识符下面,就是为了少撞名字;依赖还得作者自己管,库 A 要用库 B,就得作者自己加一个 script 标签先把 B 加载进来,还得保证顺序不错;想按需加载也难,页面一打开所有东西都被加载和初始化。模块就是来收拾这个局面的:每个模块明确声明自己依赖哪些模块、要其中的哪些变量,依赖关系从一条线变成一张图。记住判断句:脚本是大家共用一个全局作用域,模块是各自在自己的作用域里、靠 import 和 export 打交道。
第二步:先把东西交出去,具名导出
拆的第一步是交出去:一个模块想让别人用它的东西,得先 export。MDN《JavaScript modules》讲得很直白:跟脚本不一样,模块里的变量默认外面看不见,必须明确 export 才能被别的模块访问。export 关键字可以放在任何声明前面,包括 var、let、const、function、class,都得是顶层的东西,比如不能在函数里面用 export。两种写法都行:一种是直接写在声明前面,export const name = "square",export function draw(ctx, length, x, y, color) { };另一种是先声明、再用花括号列一张清单交出去,export { name, draw, reportArea, reportPerimeter }。MDN 的例子是 square.js:里面有个常量 name 存着字符串 "square",有个 draw 函数在画布上画方形,有 reportArea 和 reportPerimeter 两个函数往报告列表里写面积和周长,四个一起 export 出去。还有一条规则要记:export 声明不受暂时性死区规则限制,可以先写 export { x },后面再写 const x = 1,照样成立,因为 export 只是声明、不取 x 的值。咖啡馆的拆法就是照这个来的:menu.js 里 export const MENU 导出菜单数据,export function findDish(id) 导出按编号找菜的函数;order.js 里 export function addToOrder(dish) 导出加菜的函数。记住判断句:不 export 的东西,外面看不见;export 有两种写法,声明前加,或者文末列清单。
第三步:再把东西拿进来,具名导入
交出去之后,第二步是拿进来。MDN《JavaScript modules》的写法是 import 语句,后面跟一对花括号,里面是用逗号隔开的、想要的名字,再跟 from,最后跟模块说明符:import { name, draw, reportArea, reportPerimeter } from "./modules/square.js"。拿进来之后用起来就跟在同一个文件里定义的一样。模块说明符就是指向那个模块的字符串,在浏览器里通常是相对于当前模块的地址写成的相对地址,跟 a 标签的 href 差不多。MDN 给的例子是:main.js 在 https://example.com/basic-modules/main.js,square.js 在 https://example.com/basic-modules/modules/square.js,那么 "https://example.com/basic-modules/modules/square.js"、"/basic-modules/modules/square.js" 和 "./modules/square.js" 三种写法等价。浏览器里有一条硬规矩要记:不能省略文件扩展名和 index.js 文件名。MDN《import》页写得很清楚:跟 CommonJS 不一样,浏览器里 import x from "./utils" 不会自己去试 utils、utils/index.js、utils.js 好几个地址,写成什么样就按什么样去请求,扩展名必须写全;想让裸说明符、也就是直接写包名那种写法在浏览器里工作,得配 import maps。咖啡馆的 main.js 就是这么接的:import { MENU, findDish } from "./modules/menu.js",import { addToOrder } from "./modules/order.js",一行一个模块,依赖关系一目了然。记住判断句:具名导入名字必须对得上,路径是相对地址,.js 后缀不能省。
第四步:一个模块只能有一个默认导出
具名导出之外,还有默认导出,专门给“一个模块主要就是一个东西”的场合用。MDN《JavaScript modules》讲得很清楚:默认导出没有名字,一个模块最多只能有一个默认导出。想创建一个默认导出,不是导出一个声明,而是导出一个表达式,在前面加上 export default:export default { some: "object" },export default 1 + 1,export default randomSquare,三个都行。函数和类是特例:它们是按声明、而不是按表达式导出的,而且声明可以是匿名的,所以可以直接这样写:export default function randomSquare(ctx) { },函数声明会被提升。拿进来的时候不用花括号,名字随便起,不必跟导出那边的名字一样:import randomSquare from "./modules/square.js",randomSquare 这个名字是导入这边自己起的。具名导出和默认导出可以在同一个模块里共存。MDN《export》页还讲了一个容易混的差别:export { myFunction as default } 导出的是一个活绑定,后面再给 myFunction 重新赋值,导入那边能看到新值;而 export default myFunction 是在那一刻把 myFunction 的值取出来导出,后面再赋值,导入那边看不到。咖啡馆的例子:checkout.js 里最主要的就是一个结算函数,export default function checkout(order) { },main.js 里 import checkout from "./modules/checkout.js",名字随你起;order.js 里既有具名导出的 addToOrder,又有默认导出的 Order 类,两者共存。记住判断句:默认导出一个模块只能有一个,导入时名字随便起;要的是活绑定,用 export { x as default },要的是当时那个值,用 export default x。
第五步:名字撞了怎么办,as 改名
模块一多,名字撞车是迟早的事。MDN《JavaScript modules》举的例子很实在:方形、圆形、三角形三个模块里都有 draw、reportArea、reportPerimeter 这些同名函数,如果直接 import { name, draw, reportArea, reportPerimeter } from "./modules/square.js",再 import 同样四个名字 from "./modules/circle.js",浏览器会直接报 SyntaxError,说 import 的名字重复声明了。办法是在 import 或者 export 的花括号里用 as 关键字改名:import { name as squareName, draw as drawSquare, reportArea as reportSquareArea, reportPerimeter as reportSquarePerimeter } from "./modules/square.js",圆形那边改成 circleName、drawCircle,三角形那边改成 triangleName、drawTriangle,三个模块的同名函数在 main.js 里就各有各的名字了。也可以反过来,在导出那边的花括号里改名:export { name as squareName, draw as drawSquare, reportArea as reportSquareArea, reportPerimeter as reportSquarePerimeter },效果一样。MDN 的建议是:尽量别动模块本身的代码,在导入这边改名,尤其是在导入第三方模块、你根本改不了它代码的时候。默认导出也能用 as:import { default as randomSquare } from "./modules/square.js",因为 default 是保留字、不是合法的标识符,必须取个别名才能用。咖啡馆的教训:menu.js 和 order.js 里都有一个叫 format 的函数,一个格式化菜单、一个格式化订单,直接都 import 进来就撞了;改成 import { format as formatMenu } from "./modules/menu.js",import { format as formatOrder } from "./modules/order.js",两边井水不犯河水。记住判断句:名字撞了就用 as 改名,优先在导入这边改。
第六步:整包拿进来,命名空间导入
改名能解决问题,但名字一多就啰嗦。更干净的办法是整包拿进来:import * as Module from "./modules/module.js",把那个模块里所有导出都装进一个叫 Module 的对象里,用的时候写 Module.function1()、Module.function2()。MDN《JavaScript modules》把这个叫模块命名空间对象,例子是 import * as Canvas from "./modules/canvas.js",import * as Square from "./modules/square.js",import * as Circle from "./modules/circle.js",import * as Triangle from "./modules/triangle.js",用的时候写 Square.draw(myCanvas.ctx, 50, 50, 100, "blue"),Square.reportArea(square.length, reportList)。有两条细节要记:这个命名空间对象是密封的、原型是 null 的对象,默认导出挂在它身上、键名就叫 default,也就是说 Module.default 就是那个默认导出;另外 JavaScript 没有 import * from "module-name" 这种通配导入写法,MDN《import》页专门提醒,因为通配导入太容易撞名字。咖啡馆的 main.js 后来就是这么写的:import * as Menu from "./modules/menu.js",import * as Order from "./modules/order.js",菜单相关的都走 Menu. 开头,订单相关的都走 Order. 开头,代码读起来像在翻目录。记住判断句:一个模块的东西用得多,就整包拿进来挂个命名空间;默认导出在命名空间里叫 .default。
第七步:攒一个总入口,聚合导出与 barrel 模块
模块多了,导入的语句也会越写越长。MDN《JavaScript modules》给的办法是攒一个总入口:加一个 shapes.js,里面不干别的活,只把 circle.js、square.js、triangle.js 的导出聚到一起,这种只负责聚合的模块叫 barrel 模块。用 import 再 export 两步写是这样:import { Circle } from "./shapes/circle.js",import { Square } from "./shapes/square.js",import { Triangle } from "./shapes/triangle.js",export { Circle, Square, Triangle }。但没必要先 import 再 export,export ... from 语法一行就能直接转发:export { Square } from "./shapes/square.js",export { Triangle } from "./shapes/triangle.js",export { Circle } from "./shapes/circle.js"。还有更省事的:export * from "./shapes/square.js",把那个模块里除默认导出之外的所有具名导出都转发出来,以后 square.js 里再加了新导出,shapes.js 不用跟着改。但 MDN 提醒了两个坑:第一,export * from 不转发默认导出;第二,两个通配转发如果从不同的绑定里转出同一个名字,这个名字就含糊了,会从模块命名空间里被省略掉,直接 import { a } from "./barrel.js" 会在链接阶段就抛 SyntaxError,说这个模块里对名字 a 有冲突的星号导出。MDN《export》页的例子写得很清楚:mod1.js 导出 a 是 1,mod2.js 导出 a 是 3,barrel.js 里两个 export * from 之后,import * as ns from "./barrel.js",ns.a 是 undefined;直接 import { a } 就报错。咖啡馆的拆法:modules 目录下放 menu.js、order.js、checkout.js,再加一个 index.js 做总入口,export { MENU, findDish } from "./menu.js",export { addToOrder } from "./order.js",export { default as checkout } from "./checkout.js",main.js 只需要 import { MENU, findDish, addToOrder, checkout } from "./modules/index.js" 一行。记住判断句:总入口用 export ... from 转发,通配转发不带默认导出、同名会含糊。
第八步:只跑代码不拿东西,副作用导入与 JSON 模块
有时候导入一个模块,不是为了用它里面的东西,而是为了让它里面的代码跑一遍。MDN《JavaScript modules》讲得很清楚:想运行一个模块的初始化代码、又不导入它的任何导出,就用只有模块说明符的 import:import "./modules/polyfills.js"。这种写法叫副作用导入,常用来装 polyfill,也就是改全局变量的补丁。MDN《import》页的说法也一样:导入整个模块只为了它的副作用,运行模块的全局代码,但实际上不导入任何值。除了 JavaScript 模块,还能导入别的语言写的模块,只要运行环境知道怎么解释它们。规范只定义了另外两种资源类型:JSON 模块和文本模块。JSON 模块就是一个独立的 JSON 文件,导入进来只有一个默认导出,里面是解析好的 JSON 值,写法是 import data from "./data.json" with { type: "json" },末尾那个 with { type: "json" } 是导入属性,告诉运行环境校验加载的文件确实是 JSON。文本模块类似,导入进来是字符串:import text from "./text.txt" with { type: "text" }。MDN 建议的好习惯是:总是声明要导入的模块类型,这样代码到处都能跑。咖啡馆的例子:点单页启动时要先装一个日期补丁,main.js 第一行写 import "./modules/polyfills.js",不取任何值;菜单的静态数据放在 menu.json 里,import menuData from "./data/menu.json" with { type: "json" },拿到的就是解析好的对象。记住判断句:只跑代码不拿东西,用只有说明符的 import;JSON 模块要带 with { type: "json" }。
第九步:导入会提升,绑定是活的
import 有两个脾气,新手最容易在这上面栽跟头:它会提升,而且导入的绑定是活的。先说提升。MDN《JavaScript modules》讲得很清楚:import 声明会被提升,也就是说,导入的值在模块代码里、声明它的那一行之前就能用,而且被导入模块的副作用会在当前模块其余代码开始运行之前产生。MDN 的例子是在 main.js 中间才写 import { Canvas } from "./modules/canvas.js",前面的代码照样能用 Canvas。但 MDN 也说了,好习惯是把所有 import 都放在代码顶部,这样依赖关系一眼就能看明白。再说活绑定。MDN《import》页的例子写得很直观:my-module.js 里 export let myValue = 1,半秒之后改成 2;main.js 里 import { myValue } from "/modules/my-module.js",一开始打印是 1,一秒之后再打印就是 2——导出那边重新赋值,导入这边看到的就是新值。反过来不行:导入这边不能重新给导入的绑定赋值,写 myValue = 3 会抛 TypeError,说不能给常量赋值。导入这边只能读,不能改。但有一条要分清:改不了绑定,不等于改不了对象。导出的是一个对象,导入这边可以改这个对象的属性,改完所有导入同一个值的模块都能看到。MDN《export》页的例子是 graph 对象:main.js 里改 graph.options,调 graph.draw(),cube(3) 还是 27,对象属性的改动是共享的。咖啡馆的教训:order.js 里 export let currentTable = 1,收银台那边改成 5,点单页这边读到的就是 5,不用再传消息;但点单页这边千万别写 currentTable = 6,那是 TypeError。记住判断句:import 会提升、写顶部;导入的绑定是活的,只能读、不能重新赋值,但对象的属性可以改。
第十步:用的时候再加载,动态 import()
静态 import 有一个代价:页面一打开,所有依赖的模块都会被加载和求值。有些模块平时用不上,比如打印小票的模块,只有顾客点了“打印”才需要。MDN《JavaScript modules》给的办法是动态 import:import() 运算符接受模块的路径作参数,返回一个 Promise,兑现时给一个模块命名空间对象,从里面取导出。写法是 import("./modules/myModule.js").then((module) => { })。MDN 的例子是三个按钮——圆形、方形、三角形,点哪个按钮,才动态加载对应的模块,再画对应的图形。squareBtn.addEventListener("click", () => { import("./modules/square.js").then((Module) => { const square = new Module.Square(myCanvas.ctx, myCanvas.listId, 50, 50, 100, "blue"); square.draw(); square.reportArea(); square.reportPerimeter(); }); })。注意这里的 Module.Square:因为 Promise 兑现给的是模块命名空间对象,类就成了这个对象下面的一个属性,所以要用 Module. 打头。动态 import 还有一个好处:它随时可用,哪怕在脚本环境里也能用。也就是说,哪怕你的 HTML 里是个没有 type="module" 的普通 script 标签,也能用动态 import 把以模块形式分发的代码拿进来复用,不用先把整段代码重构成模块。MDN 也写了它的限制:在服务工作线程或者 worklet 里调用 import() 会被拒绝。咖啡馆的例子:打印模块 print.js 只有点“打印小票”时才加载,printBtn.addEventListener("click", () => { import("./modules/print.js").then((m) => m.printReceipt(order)); }),平时不占加载时间。记住判断句:用得少的模块别静态 import,点到了再用 import() 动态加载,拿到的是命名空间对象。
第十一步:顶层 await 与 import.meta,模块才有的两个帮手
模块里还有两个帮手,脚本里没有:顶层 await 和 import.meta。先说顶层 await。MDN《JavaScript modules》讲得很清楚:await 关键字可以在模块的顶层使用,不必包在 async 函数里。这意味着一个模块可以像一个大的异步函数那样行事,在依赖它的模块执行之前先把异步工作做完,又不阻塞那些不依赖它的兄弟模块。MDN 的例子是取颜色的 getColors.js:先 fetch 颜色数据,再 export default await colors,依赖这个模块的其他模块会等颜色下载和解析完再用;但不依赖它的 canvas.js 照样一边加载、一边求值,不会被拖住。MDN 也提醒了代价:顶层 await 不是免费的,它意味着模块图的一部分只能异步求值,影响不小,用之前要想清楚。再说 import.meta。每个模块都有自己的执行上下文,通过一个模块专用的 import.meta 对象来访问,它的各属性由宿主环境定义,核心语言规范不定义任何属性。在大多数类 Web 环境里,import.meta.url 给的是这个模块自己的地址,可以拿它来定位相对于这个模块的资源:const colorsURL = new URL("../data/colors.json", import.meta.url),这样不管这个模块被哪个目录下的页面或者模块导入,资源地址都还是相对于 getColors.js 自己,搬家也不会错。咖啡馆的例子:getMenu.js 里用顶层 await 先把菜单数据拉下来再导出,main.js 拿到手就是现成的;打印模板的地址用 new URL("./templates/receipt.html", import.meta.url) 来算,模块挪了目录也不用改地址。记住判断句:顶层 await 只在模块里能用,依赖它的模块会等它;import.meta.url 是模块自己的地址,算相对资源地址靠它。
第十二步:数一数写错,六种错法占了全部
下面这张图是虚构的统计:青石咖啡馆点单页把 main.js 拆成模块的一个月里 132 次拆分与引用写错,按原因分了六类,数字是编出来讲道理的,不是真实记录。排第一的是忘写 .js 后缀或者路径写错,占 32 次、24.2%,对应第三步;第二是具名导出的名字对不上,占 28 次、21.2%,对应第三、第五步;第三是默认导出当成具名导入、花括号套错了,占 24 次、18.2%,对应第四步;第四是同名导入冲突没改名,占 20 次、15.2%,对应第五步;第五是直接在导入端改导入值,占 16 次、12.1%,对应第九步;第六是直接用 file:// 打开页面、模块报跨域错误,占 12 次、9.1%,对应下面要讲的两个坑。六类加起来 32 + 28 + 24 + 20 + 16 + 12 = 132,百分比 24.2 + 21.2 + 18.2 + 15.2 + 12.1 + 9.1 = 100.0,账是平的。看这张图要看门道:排前三位的错都是“写法没对上”——后缀、名字、花括号;排后三位的错都是“规矩没记住”——活绑定不能改、file:// 不能跑模块。修模块的错,先对写法,再记规矩。
第十三步:两个坑与自查清单,写完模块代码先过一遍
最后讲两个坑,都是 MDN《export》页和《JavaScript modules》页白纸黑字写着的。第一个坑:不能用 file:// 地址直接跑 JavaScript 模块,会报跨域错误,得用 HTTP 服务器跑。MDN《export》页的原话是:你没法通过 file:// 地址运行 JavaScript 模块,会得到跨域错误,需要通过 HTTP 服务器运行。本地开发起一个静态服务器再打开页面,这个问题就消失了。第二个坑:服务器必须用 JavaScript 的 MIME 类型提供模块文件。MDN《JavaScript modules》讲得很清楚:想让模块在浏览器里正常工作,得确保服务器返回的 Content-Type 头里含有 JavaScript 的 MIME 类型,比如 text/javascript;如果不是,会报严格 MIME 类型检查错误,浏览器不会运行这段 JavaScript。大多数服务器对 .js 文件会自动给对,但对 .mjs 文件有些服务器不会给对,这是 MDN 建议开发时用 .js、构建时再转 .mjs 的原因之一。自查清单一共九条:第一,模块里声明的东西,export 了吗,没 export 的外面看不见。第二,具名导入的名字,和导出那边对得上吗。第三,路径里的 .js 后缀写全了吗,相对地址算对了吗。第四,默认导出一个模块只有一个吗,导入时花括号用对了吗。第五,同名导入改名了吗,优先在导入这边改。第六,一个模块的东西用得多,整包拿进来挂命名空间了吗。第七,总入口的转发里,默认导出要不要单独转,通配转发会不会撞名字。第八,导入的绑定只读不改,改的是对象的属性吗。第九,用得少的模块改成动态 import 了吗,页面是走 HTTP 服务器打开的吗。九条都过了,这段模块代码才算写完;过不了的,回去改,别指望浏览器报错时再猜。
评论 (0)
原始来源
相关文章
Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。
一张点单就是一个对象:桌号、菜品、总价、付没付钱,全按标签收在一起。本文按 MDN 的《Working with objects》《JSON》《Object》三篇官方文档讲清楚:对象字面量、点号与方括号、增删改查、for...in 配 hasOwn、方法与 this、getter 与 setter、引用与复制、Object.assign 等工具箱、空白原型对象、JSON 的严规矩,以及 stringify 与 parse 和数字精度的坑。
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。