企业官网建设流程全解析

• 文档
• 教程
• 后端

导读

在 Koa2 学习笔记项目（koa2-note）中，note/other/esm.md专题讲解了如何在 Node 9 的 flag 模式下直接使用ECMAScript Modules（即import/export语法）来编写和运行 Koa2 应用，从而摆脱 babel 等转译工具的束缚。本文将完整梳理这套方案的使用须知、与require()的差异对比、Loader Hooks 的加载原理，并结合仓库中 demo/esm 目录下的真实源码，逐步演示如何通过自定义 loader 规则让 Koa2 应用同时加载*.js、*.json文件乃至 npm 模块。读完本文，你将掌握 Node 9.x 时代下import/export的原生使用姿势，以及 Resolve Hook 自定义规则的核心写法。

背景：Node 9 的 flag 模式与 ECMAScript Modules

Node 9 最令人激动的新特性之一，是提供了在 flag 模式下使用ECMAScript Modules的能力。虽然该特性当时仍处于Stability: 1 - Experimental（实验阶段），但足以让 Node 开发者抛掉 babel 等工具的束缚，直接在 Node 环境下愉快地使用import/export语法。

在 note/other/esm.md 的配套实践中，Koa2 应用可以不经过任何转译，直接以原生 ES Module 语法书写并运行，例如：

import Koa from 'koa'; import { render } from './lib/render.js'; import data from './lib/data.json';

这段代码正是仓库中 demo/esm/index.js 的入口内容，它同时用import加载了 npm 模块（koa）、*.js文件（render.js）和*.json文件（data.json）——而这三种类型的加载，恰好对应了下文 Loader Hooks 需要解决的核心问题。

Node 9 下 import/export 使用简单须知

在原文档中，使用import/export需要满足以下硬性条件，这些条件在仓库 demo/esm/package.json 中也有对应体现（其engines字段明确声明"node": ">= 9.0.0"）：

1. Node 环境必须在 9.0 以上——低于 9.0 的版本没有 flag 模式支持；
2. 不加 loader 时，使用import/export的文件后缀名必须为*.mjs——这是 Node 对 ES Module 文件与 CommonJS 文件做区分的默认约定（下文会讲到利用 Loader Hooks 兼容*.js后缀文件）；
3. 启动必须加上 flag--experimental-modules——这是开启 ES Module 实验特性的开关；
4. 文件的import和export必须严格按照ECMAScript Modules语法——不能混用require/module.exports的写法；
5. ECMAScript Modules和require()的 cache 机制不一样——两者各自维护独立的缓存，import的缓存目前不可访问。

注：本专题基于 Node 9.x 时代的技术背景写成。Node 官方在后续版本中对 ES Module 的支持持续演进（如--experimental-modules的逐步稳定、package.json中"type": "module"字段的引入等），但本笔记保留的是当时的真实用法，适用前提为 Node 9.x + flag 模式。

与 require() 的区别对照

原文档给出了一张非常实用的能力对照表，逐项对比require()与import在模块加载能力上的差异。这张表是理解 Loader Hooks 设计动机的关键：

从表中可以提炼出两个核心结论：

• 路径体系不同：require()使用文件系统路径，而import使用 URL 格式路径（甚至允许带查询参数，如./a?v=2017）；
• 扩展名机制不同：require()靠require.extensions扩展，而import的扩展名规则要靠Loader Hooks来接管——这正是下一节要深入展开的内容。

Loader Hooks 模式：让 import/export 拥抱整个 Node 生态

为什么需要 Loader Hooks

在 ES6 的 Modules 规范确定之前，JavaScript 的模块化处理方案处于“八仙过海、各显神通”的状态：前端有 AMD、CMD 模块方案，Node 的 CommonJS 方案也在这个“乱世”中诞生。当 ES6 规范确定后，Node 的 CommonJS 方案已经是 JavaScript 生态中比较成熟的模块化方案，但 ES6 毕竟是“正统”规范，从“法理”上 Node 需要兼容它，于是*.mjs这个针对ECMAScript Modules规范的 Node 文件方案应运而生。

但问题也随之而来：如果import/export只能对*.mjs文件起作用，那么 Node 原生模块和 npm 上所有第三方模块都无法使用。为此，Node 9 提供了Loader Hooks机制，允许开发者自定义Resolve Hook规则，利用import/export加载 Node 原生模块、*.js文件、npm 模块、C/C++ 编写的 Node 编译模块等整个 Node 生态圈的模块。

Loader Hooks 使用步骤

原文档给出的使用步骤非常精简，只有两步：

1. 自定义 loader 规则——编写一个.mjs格式的 loader 文件；
2. 启动时用 flag 加载 loader 规则文件，例如：

node --experimental-modules --loader ./custom-loader.mjs ./index.js

这条启动命令被原样固化在了仓库的 demo/esm/package.json 中（scripts.start字段），也就是说进入demo/esm目录后执行npm start即可复现同样的效果。

Koa2 直接使用 import/export 实战

项目文件目录

原文档展示了配套 demo 的目录结构（对应仓库中的 demo/esm）：

├── esm │ ├── custom-loader.mjs │ ├── index.js │ ├── lib │ │ ├── data.json │ │ ├── path.js │ │ └── render.js │ ├── package.json │ └── view │ ├── helloworld.html │ ├── index.html │ └── todo.html

各文件职责如下：

• custom-loader.mjs：自定义 Loader Hooks 规则，负责把import解析能力扩展至*.js、*.json与 npm 模块；
• index.js：Koa2 应用入口，使用import语法编写；
• lib/render.js：封装读取view目录下 HTML 模板的渲染函数；
• lib/path.js：通过process.cwd()导出项目根路径PROJECT_PATH；
• lib/data.json：JSON 数据文件，用于演示import data from './lib/data.json'的 JSON 加载能力；
• view：index.html、helloworld.html、todo.html三个页面模板。

主文件源码

原文档指出“代码片段太多，不一一贴出来，只显示主文件”，主文件（即 demo/esm/index.js）完整代码如下：

import Koa from 'koa'; import { render } from './lib/render.js'; import data from './lib/data.json'; let app = new Koa(); app.use((ctx, next) => { let view = ctx.url.substr(1); let content; if ( view === '' ) { content = render('index'); } else if ( view === 'data' ) { content = data; } else { content = render(view); } ctx.body = content; }) app.listen(3000, ()=>{ console.log('the modules test server is starting'); })

这段代码同时示范了三种import形态：

• import Koa from 'koa'——加载 npm 第三方模块（依赖 Loader Hooks 中的 npm 判断分支）；
• import { render } from './lib/render.js'——以命名导出方式加载*.js文件（对应 Loader Hooks 的esm格式分支）；
• import data from './lib/data.json'——以默认导出方式加载*.json文件（对应 Loader Hooks 的json格式分支）。

路由逻辑也很直观：根据ctx.url去掉首字符后的值决定渲染哪个视图；data路径直接返回 JSON 对象，其余路径则交给render()从view目录读取对应 HTML 文件。结合 lib/render.js 的源码可以看到，render内部通过path.join(PROJECT_PATH, 'view',${view}.html)拼接模板路径，文件存在则用fs.readFileSync读取并以binary编码返回，不存在则返回Error: file ${view}.html is not found!提示——这是一个兼顾健壮性的小型模板渲染实现。

执行与访问

执行代码：

node --experimental-modules --loader ./custom-loader.mjs ./index.js

然后访问以下地址验证效果：

• 访问http://127.0.0.1:3000/index——返回index.html页面内容；
• 访问http://127.0.0.1:3000/data——直接返回 lib/data.json 中的 JSON 数据（{"title": "hello ES6 Modules", "name": "ES6"}）；
• 访问http://127.0.0.1:3000/todo——返回todo.html页面内容。

仓库 demo/esm/package.json 中已配置好一键启动脚本"start": "node --experimental-modules --loader ./custom-loader.mjs ./index.js"，因此在实际操作时直接运行npm start即可，无需手敲完整命令。

自定义 loader 规则优化：覆盖 npm 模块与 JSON 文件

为什么要优化

官方示例中的自定义 loader 只对*.js文件做了import/export兼容，但在实际开发中，我们往往还需要对 npm 模块、*.json文件也使用import/export。仓库 demo/esm/custom-loader.mjs 正是原文档中“优化版”loader 的完整落地实现，下面结合源码逐段解析。

loader 规则优化解析

首先，loader 文件本身就是一个 ES Module（.mjs后缀），顶部使用import引入 Node 原生模块：

import url from 'url'; import path from 'path'; import process from 'process'; import fs from 'fs';

第一步：收集项目所需的 npm 模块信息。通过读取当前工作目录下的package.json，把dependencies与devDependencies合并为一个allDependencies对象，供后续判断某个import的模块名是否为 npm 模块：

// 从package.json中 // 的dependencies、devDependencies获取项目所需npm模块信息 const ROOT_PATH = process.cwd(); const PKG_JSON_PATH = path.join( ROOT_PATH, 'package.json' ); const PKG_JSON_STR = fs.readFileSync(PKG_JSON_PATH, 'binary'); const PKG_JSON = JSON.parse(PKG_JSON_STR); // 项目所需npm模块信息 const allDependencies = { ...PKG_JSON.dependencies || {}, ...PKG_JSON.devDependencies || {} }

第二步：收集 Node 原生模块清单。利用process.binding('natives')拿到 Node 内部注册的全部模块名，并用正则过滤掉internal、node、v8前缀的内部模块，存入builtins集合：

//Node原生模信息 const builtins = new Set( Object.keys(process.binding('natives')).filter((str) => /^(?!(?:internal|node|v8)\/)/.test(str)) );

第三步：定义兼容的文件扩展名集合。这里把*.js、*.mjs归为 JS 文件，*.json单独归为一类：

// 文件引用兼容后缀名 const JS_EXTENSIONS = new Set(['.js', '.mjs']); const JSON_EXTENSIONS = new Set(['.json']);

第四步：导出resolve函数实现 Resolve Hook。这是整个 loader 的核心，resolve接收三个参数：specifier（被 import 的模块标识符）、parentModuleURL（父模块的 URL）、defaultResolve（Node 默认的解析函数）。其分支逻辑依次覆盖四类场景：

export function resolve(specifier, parentModuleURL, defaultResolve) { // 判断是否为Node原生模块 if (builtins.has(specifier)) { return { url: specifier, format: 'builtin' }; } // 判断是否为npm模块 if ( allDependencies && typeof allDependencies[specifier] === 'string' ) { return defaultResolve(specifier, parentModuleURL); } // 如果是文件引用，判断是否路径格式正确 if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) { throw new Error( `imports must begin with '/', './', or '../'; '${specifier}' does not`); } // 判断是否为*.js、*.mjs、*.json文件 const resolved = new url.URL(specifier, parentModuleURL); const ext = path.extname(resolved.pathname); if (!JS_EXTENSIONS.has(ext) && !JSON_EXTENSIONS.has(ext)) { throw new Error( `Cannot load file with non-JavaScript file extension ${ext}.`); } // 如果是*.js、*.mjs文件 if (JS_EXTENSIONS.has(ext)) { return { url: resolved.href, format: 'esm' }; } // 如果是*.json文件 if (JSON_EXTENSIONS.has(ext)) { return { url: resolved.href, format: 'json' }; } }

规则总结

在原文档的总结中，自定义 loader 里export的resolve规则最核心的代码是：

return { url: '', format: '' }

两个返回字段的含义如下：

• url：模块名称或者文件 URL 格式路径；
• format：模块格式，共有esm、cjs、json、builtin、addon五种取值，分别对应 ES Module、CommonJS、JSON、Node 原生内建模块、C/C++ 编译扩展（addon）模块。

对照仓库源码可以看到，resolve函数的四个分支正好覆盖了format的三种取值：原生模块返回builtin，*.js/*.mjs文件返回esm，*.json文件返回json；而 npm 模块直接委托给defaultResolve处理（默认解析会走 npm 模块自己的包内格式）。这也解释了文章开头那张对比表中“npm 模块引用需要 Loader Hooks”的原因——只有通过自定义 Resolve Hook，import才能获得接近require()的加载能力。

注意事项与适用边界

原文档最后给出了明确的提醒，这一点在今天依然具有方法论价值：

• 目前 Node 对import/export的支持仍处于Stability: 1 - Experimental（实验阶段），后续发展存在很多不确定因素；
• 自己练手玩玩可以，但在还没去掉 flag 使用之前，尽量不要在生产环境中使用；
• 本专题配套 demo 的完整源码位于仓库 demo/esm 目录，可直接对照 index.js、custom-loader.mjs 与 package.json 自行运行验证（npm install后执行npm start，再访问127.0.0.1:3000下的/index、/data、/todo路径）。

结语

通过本篇笔记可以看到，Node 9 时代的import/export虽然挂着“实验性”标签，但其技术骨架已经相当完整：*.mjs文件约定解决了 ES Module 与 CommonJS 的格式区分问题，Loader Hooks 机制则通过自定义 Resolve Hook 把import的触角延伸到了 npm 模块、*.json文件乃至原生模块。结合 koa2-note 仓库中 demo/esm 的完整实现，你既可以一键复现“零转译运行 Koa2 应用”的效果，也能深入理解 Resolve Hook 返回{ url, format }的核心原理。这套“flag + loader 规则”的组合，正是 Node 原生 ES Module 支持在早期落地时的经典范本。

• 文档
• 教程
• 后端