Sea.js 的 loader 是整个框架的心脏。這篇聚焦在 module.js:一個模組從被請求、被下載、被記錄、到最後被編譯執行的完整生命週期,以及 CMD 規範中「依賴先於 factory 執行」這件事究竟怎麼被保證的。
理解整份程式碼的鑰匙是這個狀態表:
var STATUS = {
'FETCHING': 1, // 模組檔案正在下載中
'FETCHED': 2, // 模組檔案已下載
'SAVED': 3, // 模組資訊已保存(依賴已解析)
'READY': 4, // 自身與所有依賴都已就緒,等待編譯
'COMPILING': 5, // 模組正在編譯中
'COMPILED': 6 // 已編譯,module.exports 可用
};
每個模組都是一個 Module 實例,屬性依生命週期逐步補上:
function Module(uri, status) {
this.uri = uri;
this.status = status || 0;
// this.id → save 時設定
// this.dependencies → save 時設定
// this.factory → save 時設定
// this.exports → compile 時設定
// this.parent → compile 時設定
// this.require → compile 時設定
}
注意 uri 才是內部識別用的鍵,id 只是使用者寫的名字。這個區分是後面所有查表邏輯的基礎。
Module.prototype._use = function (ids, callback) {
util.isString(ids) && (ids = [ids]);
// 用系統內部的路徑解析機制把 id 轉成 uri
var uris = resolve(ids, this.uri);
this._load(uris, function () {
// 編譯前再處理一次 preload:
// 因為程式執行期間隨時可能呼叫 seajs.config 設定預載入模組
preload(function () {
var args = util.map(uris, function (uri) {
return uri ? cachedModules[uri]._compile() : null;
});
if (callback) {
callback.apply(null, args); // null 使 this 指向 window
}
});
});
};
這裡有個關鍵設計:_use 不直接回傳 exports,而是把它們當參數餵給 callback。這是因為非同步載入的本質——呼叫當下依賴還沒回來,沒東西可回傳。對應到使用者層,就是 seajs.use('a', function(a){ … }) 那個回呼。
Module.prototype._load = function (uris, callback) {
// 只保留「還沒準備好」的模組
var unLoadedUris = util.filter(uris, function (uri) {
return uri && (!cachedModules[uri] ||
cachedModules[uri].status < STATUS.READY);
});
var length = unLoadedUris.length;
// 全都就緒了,直接進入編譯
if (length === 0) {
callback();
return;
}
var remain = length;
for (var i = 0; i < length; i++) {
// 閉包:為 onFetched 提供各自的 uri 上下文
(function (uri) {
var module = cachedModules[uri] ||
(cachedModules[uri] = new Module(uri, STATUS.FETCHING));
module.status >= STATUS.FETCHED ? onFetched() : fetch(uri, onFetched);
function onFetched() {
module = cachedModules[uri];
if (module.status >= STATUS.SAVED) {
// 依賴清單已經確定,繼續往下抓
var deps = getPureDependencies(module);
if (deps.length) {
Module.prototype._load(deps, function () { cb(module); });
} else {
cb(module);
}
} else {
// 404、非模組格式等失敗情況,直接放行;
// 編譯該模組時會回傳 null
cb();
}
}
})(unLoadedUris[i]);
}
function cb(module) {
(module || {}).status < STATUS.READY && (module.status = STATUS.READY);
--remain === 0 && callback();
}
};
這段是整個 loader 的骨架,值得逐點欣賞:
(function(uri){…})(unLoadedUris[i]) 是必要的,否則所有非同步回呼都會共用迴圈結束後的最後一個 uri。
Module.prototype._compile = function () {
var module = this;
if (module.status === STATUS.COMPILED) {
return module.exports; // 編譯過就直接回傳,冪等
}
// 404、格式不合法等異常,回傳 null
if (module.status < STATUS.SAVED && !hasModifiers(module)) {
return null;
}
module.status = STATUS.COMPILING;
// 模組內部用來同步取得其他模組的介面
function require(id) {
var uri = resolve(id, module.uri);
var child = cachedModules[uri];
if (!child) return null;
// 避免循環依賴反覆編譯
if (child.status === STATUS.COMPILING) {
return child.exports;
}
child.parent = module; // 記錄呼叫來源,可還原 Call Stack
return child._compile();
}
require.async = function (ids, callback) { module._use(ids, callback); };
require.resolve = function (id) { return resolve(id, module.uri); };
require.cache = cachedModules;
module.require = require;
module.exports = {};
var factory = module.factory;
if (util.isFunction(factory)) {
compileStack.push(module);
runInModuleContext(factory, module);
compileStack.pop();
} else if (factory !== undefined) {
// define({...}) 或 define('字串') 這種直接暴露值的寫法
module.exports = factory;
}
module.status = STATUS.COMPILED;
execModifiers(module);
return module.exports;
};
三個值得記住的細節:
define({ "foo": "bar" }) 能動的原因。CMD 的 define 吃很多種簽名,靠參數個數與型別分派:
Module._define = function (id, deps, factory) {
var argsLength = arguments.length;
if (argsLength === 1) {
// define(factory)
factory = id; id = undefined;
}
else if (argsLength === 2) {
// 預設當成 define(id, factory)
factory = deps; deps = undefined;
// 但如果是 define(deps, factory)
if (util.isArray(id)) {
deps = id; id = undefined;
}
}
// 沒寫 deps 時,用正則從 factory.toString() 中抓 require('xxx')
if (!util.isArray(deps) && util.isFunction(factory)) {
deps = util.parseDependencies(factory.toString());
}
var meta = { id: id, dependencies: deps, factory: factory };
// …後續決定 uri 並 save
};
util.parseDependencies 就是所謂的「依賴自動分析」——把函式轉成字串再用正則撈出 require('...')。這是 Sea.js 相比 RequireJS 的一大便利,代價是靜態分析天生有極限(拿不到的情況就退回手動宣告 deps)。
匿名模組的 uri 推導在 IE6-9 上特別麻煩,需要靠 document.attachEvent 時的 interactive script 去拿 currentScript,失敗時才退回 onload 事件。這段充滿相容性分支的程式碼,正是那個年代的印記。
function fetch(uri, callback) {
var requestUri = util.parseMap(uri); // 套用 map 規則
// 已下載過,直接執行回呼
if (fetchedList[requestUri]) {
cachedModules[uri] = cachedModules[requestUri];
callback();
return;
}
// 正在下載中,只需把 callback 掛進佇列
if (fetchingList[requestUri]) {
callbackList[requestUri].push(callback);
return;
}
fetchingList[requestUri] = true;
callbackList[requestUri] = [callback];
Module._fetch(requestUri, function () {
fetchedList[requestUri] = true;
var module = cachedModules[uri];
if (module.status === STATUS.FETCHING) {
module.status = STATUS.FETCHED;
}
// 匿名模組:此時才從閉包拿到 uri,補做 save
if (anonymousModuleMeta) {
save(uri, anonymousModuleMeta);
anonymousModuleMeta = null;
}
delete fetchingList[requestUri];
// 依序執行所有等待中的回呼
if (callbackList[requestUri]) {
util.forEach(callbackList[requestUri], function (fn) { fn(); });
delete callbackList[requestUri];
}
}, config.charset);
}
三個清單的分工很清楚:fetchingList 去重(避免同一檔案發兩次請求)、fetchedList 快取、callbackList 收集等待者。這個「請求去重 + 回呼廣播」的結構,在任何需要非同步資源的系統裡都會用到。
function getPureDependencies(module) {
return util.filter(module.dependencies, function (dep) {
circularCheckStack = [module.uri];
var isCircular = isCircularWaiting(cachedModules[dep]);
if (isCircular) {
circularCheckStack.push(module.uri);
printCircularLog(circularCheckStack);
}
return !isCircular;
});
}
function isCircularWaiting(module) {
// 模組不存在,或狀態已不是 SAVED,都無法判定
if (!module || module.status !== STATUS.SAVED) return false;
circularCheckStack.push(module.uri);
var deps = module.dependencies;
if (deps.length) {
// 第一層:直接與檢查棧重疊
if (isOverlap(deps, circularCheckStack)) return true;
// 更深層:遞迴往下查
for (var i = 0; i < deps.length; i++) {
if (isCircularWaiting(cachedModules[deps[i]])) return true;
}
}
circularCheckStack.pop();
return false;
}
function isOverlap(arrA, arrB) {
var arrC = arrA.concat(arrB);
return arrC.length > util.unique(arrC).length; // 有重複即代表繞回來了
}
這裡有個很成熟的判斷:只在 module.status === STATUS.SAVED 時才做循環檢查。因為狀態是 SAVED 代表它的資訊(含依賴清單)已經齊全,即使真的形成循環,require 時也能正常編譯並回傳介面,不會出錯——所以這種情況不值得報警。真正需要警惕的是資訊還不完整時就繞回原點。
isOverlap 用「合併後去重、長度變短就是有重複」來判斷交集,是個簡潔的小技巧。
// 全域模組,可視為「頁面模組」,初始狀態就是 COMPILED
var globalModule = new Module(util.pageUri, STATUS.COMPILED);
seajs.use = function (ids, callback) {
preload(function () {
globalModule._use(ids, callback);
});
return seajs; // 鏈式呼叫
};
seajs.define = Module._define;
seajs.cache = Module.cache;
seajs.find = Module._find;
seajs.modify = Module._modify;
// 供外掛開發者使用
seajs.pluginSDK = { Module: Module, util: util, config: config };
把頁面本身建模成一個已編譯的 Module,是很漂亮的一手:這樣 seajs.use 就只是「呼叫頁面模組的 _use」,整個載入流程不必為「入口」特例處理。
最後要說的是時代背景。Sea.js 代表的 CMD 規範與非同步依賴思路,在 2012~2016 年間解決了前端模組化的大量問題,但隨著瀏覽器原生支援 ES Modules(import / export)、npm 與打包工具(webpack、Vite、Rollup)成熟,Sea.js 已逐步退出主流;阿里也在 2019 年前後停止維護。今天讀它的價值在於三點:理解模組系統「為什麼需要」狀態機、認識非同步資源去重的通用手法、以及明白「依賴必須先於宣告它的 factory 執行」這個約束是怎麼被程式碼保證的。這些觀念在讀 webpack 的 runtime 或任何 ESM loader 時,都會再出現一次。