从脚本到模块
本合集目录
本章目录
单册说明:本文件是卷 3 的第 4 章,可独立阅读。前置:卷 2 第 7 章(三个文件)与本章之前的 Git 三章。本章把
app.js拆成四个模块,并解释为什么拆完之后双击index.html会打不开——这不是你写错了,是浏览器的安全规则。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 3 · 工程化与版本控制(第 4 / 7 章) |
| 前置章节 | 3.3 GitHub:远程与协作 |
| 本章产出 | js/ 下四个模块(store / render / events / main)· 一份依赖方向图 · 一个能在 127.0.0.1 跑通的页面 |
| 对应代码 | dudao/index.html、dudao/js/*.js(styles.css 不动) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能画出四个模块谁 import 谁;看到 Failed to resolve module specifier 知道少了 ./ |
3.4.1 一句话结论:拆模块是把"隐式顺序"变成"显式声明"
一个 600 行的 app.js 不是"长",是没有任何地方写着谁依赖谁。你只能靠阅读顺序猜:renderList 定义在 init 之前还是之后?notes 这个变量被哪几个函数偷偷改了?拆成模块之后,每个文件顶部那几行 import 就是答案——依赖成了代码的一部分,而不是记忆的一部分。
真实失败场景:卷 2 的 app.js 里你写了 function renderTags(),后来加标签筛选时又写了一个 function renderTags()(想着"反正旧的不用了")。后一个覆盖前一个,标签栏的点击回调还绑在旧函数上,于是点标签有反应、列表不刷新。控制台没有任何报错。这种 bug 靠读代码几乎找不到,因为两段代码各自都对。
3.4.2 原理:ESM 到底规定了什么
① 一个大文件会烂在三处
| 烂法 | 具体表现 | 拆开之后 |
|---|---|---|
| 作用域污染 | 所有顶层变量共享一个作用域,重名就覆盖 | 每个文件一个模块作用域,不 export 外面看不见 |
| 加载顺序靠人肉 | <script> 标签顺序错了就 undefined |
import 就是声明,浏览器按依赖图加载 |
| 改动影响面不可见 | 改一个函数,不知道谁会受影响 | 看谁 import 了它,影响面一目了然 |
第三点最值钱。工程化不是让代码"看起来专业",是让**"我改这里会坏哪里"这个问题有答案**。
② export 与 import 的四种组合
ESM(ECMAScript Modules)是语言标准,不是某个工具的发明。它只有两种导出、三种导入:
// 具名导出:一个文件可以有多个,名字必须对上
export function loadNotes() {}
export const STORAGE_KEY = 'dudao.notes';
// 默认导出:一个文件最多一个,导入时可任意起名
export default function createApp() {}
// 1. 具名导入,名字必须与导出完全一致
import { loadNotes, STORAGE_KEY } from './store.js';
// 2. 重命名,解决两个模块同名的问题
import { renderList as renderNoteList } from './render.js';
// 3. 命名空间导入,把整个模块收进一个对象
import * as store from './store.js';
store.loadNotes();
// 4. 默认导入,名字自取
import createApp from './app.js';
// 5. 副作用导入:不要任何绑定,只为执行一次(CSS、polyfill)
import './styles.css';
| 写法 | 导出方 | 导入方 | 适用 |
|---|---|---|---|
| 具名 | export function f |
import { f } |
首选。名字固定,重构时编辑器能跟 |
| 默认 | export default f |
import 任意名 |
一个文件只提供一个主东西时 |
| 命名空间 | — | import * as ns |
调试、或需要动态访问多个导出 |
| 副作用 | 无导出 | import './x.css' |
只为执行,典型是样式 |
团队项目里优先具名导出。 默认导出的名字由导入方决定,同一个东西在不同文件里可能叫 render、renderer、draw,搜代码时搜不到。
③ 模块作用域:三个变化
| 变化 | 含义 | 实际影响 |
|---|---|---|
顶层变量不再挂到 window |
以前 var notes = [] 等于 window.notes,现在只是模块内的局部变量 |
两个文件可以同名,不再互相覆盖 |
| 自动严格模式 | 不加 'use strict' 也是严格模式 |
给未声明变量赋值会直接报错,而不是静默建全局 |
| 只执行一次 | 同一个模块被多处 import,只求值一次,之后共享同一份导出 | 适合放单例状态;也意味着模块顶层别写有副作用的代码 |
第三条有个常见误解:"只执行一次"不等于"导出的是快照"。 导出的如果是对象,所有导入方拿到的是同一个引用,改它的属性彼此可见;导出的如果是 let 变量,导入方看到的是实时值,但不能给它赋值。
④ 循环依赖:为什么会拿到 undefined
A 导入 B、B 又导入 A,就构成循环。浏览器不会死循环,它会按深度优先把能执行的先执行完,于是某一方在对方还没初始化完时就被取用了。
// a.js
import { b } from './b.js';
export const a = 'A';
console.log(b); // 可能拿到 undefined
// b.js
import { a } from './a.js';
export const b = 'B';
如果取用的是 const / let 声明(而不是函数声明),还会撞上"暂时性死区",直接抛:
Uncaught ReferenceError: Cannot access 'a' before initialization
解法不是改 import 顺序,是改依赖方向。 循环依赖几乎总意味着职责切错了:两个模块互相需要,说明有一块共同的东西该被抽到第三个模块里。本项目刻意设计成单向:main → store / render / events,后三个互不引用。
⑤ 为什么必须走 HTTP
这是本章最反直觉的一节。你把 index.html 从文件夹里双击打开,地址栏是 file:///E:/code/dudao/index.html。此时页面能显示,但 <script type="module"> 会被浏览器拒绝:
Access to script at 'file:///E:/code/dudao/js/main.js' from origin 'null'
has been blocked by CORS policy: Cross origin requests are only supported
for protocol schemes: chrome, chrome-extension, chrome-untrusted, data,
http, https, isolated-app.
不同浏览器版本列出的协议清单不完全一致,但 from origin 'null' 与 blocked by CORS policy 这两段是固定的——看到它们就是"文件被当成了无源页面"。
原因是:模块脚本必须按 CORS 规则跨源请求,而 file:// 页面的源是 null,无法通过任何 CORS 检查。普通 <script src> 不受这条限制(它是"经典脚本",历史遗留的宽松规则),所以卷 2 的 app.js 双击能跑,一改成 type="module" 就白屏。
这不是 bug,是设计。 模块能 import 任意路径的文件,如果 file:// 也放行,任何下载下来的 HTML 都能读取你硬盘上的任意 JS。必须有一个"源"的概念才能限制它。
所以从这一章起,你的开发方式变了:永远通过 HTTP 打开页面。 最小的办法是用 Python 自带的服务器(不需要装任何东西):
py -m http.server 8000 # Windows
python3 -m http.server 8000 # macOS / Linux
然后访问 http://127.0.0.1:8000/。第 6 章会换成 Vite 的开发服务器,但原理完全一样。
⑥ 目录按什么分
| 分法 | 长什么样 | 优点 | 缺点 |
|---|---|---|---|
| 按类型 | js/、css/、images/ |
好找文件,新手熟悉 | 加一个功能要动三个目录 |
| 按功能 | notes/、tags/、stats/ |
一个功能的代码在一起,删功能删一个目录 | 小项目会显得目录很多 |
本阶段按"层"分:数据、渲染、事件、入口。理由是「读到」现在还小,按功能分会出现三个只有十几行的目录。等卷 4 用了框架、一个功能横跨组件与数据时,再转向按功能分——目录结构跟着规模变,不要一次定终身。
| 文件 | 职责 | 允许 import 谁 |
|---|---|---|
store.js |
读写 localStorage、构造笔记对象、汇总标签 |
不 import 本项目任何模块 |
render.js |
把数据变成 DOM,纯输出 | 不 import 本项目任何模块 |
events.js |
绑定表单与点击,把"用户做了什么"转成回调 | 不 import 本项目任何模块 |
main.js |
持有状态,串起上面三个 | 全部 |
这张表就是依赖方向图。规则只有一条:箭头只能从上往下,不能反过来。 store.js 里出现 document.querySelector 就是越界——数据层不该知道页面长什么样。
3.4.3 动手:把 app.js 拆成四个文件
第 1 步:建目录,先搬不改
mkdir js
把 app.js 里的代码分类剪切到四个新文件。这一步不重写逻辑,只搬运,搬完再跑一次确认没坏——重构的第一原则是每一步都可验证。
第 2 步:js/store.js
const STORAGE_KEY = 'dudao.notes';
export function loadNotes() {
try {
const raw = localStorage.getItem(STORAGE_KEY);
return raw ? JSON.parse(raw) : [];
} catch (error) {
console.warn('本地数据无法解析,按空列表处理', error);
return [];
}
}
export function saveNotes(notes) {
localStorage.setItem(STORAGE_KEY, JSON.stringify(notes));
}
export function createNote({ title, content, sourceUrl, tags }) {
return {
id: crypto.randomUUID(),
title: title.trim(),
content: content.trim(),
sourceUrl: sourceUrl.trim(),
tags: tags
.split(/[,,\s]+/)
.map((tag) => tag.trim())
.filter(Boolean),
createdAt: new Date().toISOString(),
};
}
export function allTags(notes) {
const set = new Set();
notes.forEach((note) => note.tags.forEach((tag) => set.add(tag)));
return [...set].sort((a, b) => a.localeCompare(b, 'zh-CN'));
}
注意 JSON.parse 被 try 包住:localStorage 里可能是用户手改过的、或旧版本留下的脏数据,解析失败不该让整个页面白屏。
还有一个隐藏条件:crypto.randomUUID() 只在安全上下文里存在,也就是 https 或 localhost / 127.0.0.1。如果你用局域网 IP 打开页面,会报 crypto.randomUUID is not a function。开发时坚持用 127.0.0.1,不只是习惯问题。
第 3 步:js/render.js
const segmenter = new Intl.Segmenter('zh-CN', { granularity: 'word' });
const STOP_WORDS = new Set(['的', '了', '是', '在', '和', '就', '不', '也', '有', '我', '你', '他', '这', '那']);
export function renderList(listEl, notes) {
listEl.replaceChildren();
if (notes.length === 0) {
const empty = document.createElement('li');
empty.className = 'empty';
empty.textContent = '还没有摘录,粘贴一段试试。';
listEl.append(empty);
return;
}
const frag = document.createDocumentFragment();
notes.forEach((note) => frag.append(noteItem(note)));
listEl.append(frag);
}
function noteItem(note) {
const item = document.createElement('li');
item.className = 'note';
const title = document.createElement('h2');
title.textContent = note.title;
const body = document.createElement('p');
body.textContent = note.content;
item.append(title, body);
if (note.sourceUrl) {
const link = document.createElement('a');
link.href = note.sourceUrl;
link.textContent = '来源';
link.target = '_blank';
link.rel = 'noreferrer noopener';
item.append(link);
}
if (note.tags.length > 0) {
const tags = document.createElement('ul');
tags.className = 'note-tags';
note.tags.forEach((tag) => {
const cell = document.createElement('li');
cell.textContent = `#${tag}`;
tags.append(cell);
});
item.append(tags);
}
return item;
}
export function renderTagBar(barEl, tags, activeTag) {
barEl.replaceChildren();
['全部', ...tags].forEach((tag) => {
const btn = document.createElement('button');
btn.type = 'button';
btn.dataset.tag = tag;
btn.className = tag === activeTag ? 'tag tag--active' : 'tag';
btn.textContent = tag;
barEl.append(btn);
});
}
export function renderStats(statsEl, notes) {
const words = topKeywords(notes, 5);
const text = words.map(([word, count]) => `${word}(${count})`).join('、');
statsEl.textContent = `共 ${notes.length} 条 · 高频词:${text || '暂无'}`;
}
function topKeywords(notes, limit) {
const counts = new Map();
notes.forEach((note) => {
const text = `${note.title} ${note.content}`;
for (const { segment, isWordLike } of segmenter.segment(text)) {
if (!isWordLike || segment.length < 2 || STOP_WORDS.has(segment)) continue;
counts.set(segment, (counts.get(segment) ?? 0) + 1);
}
});
return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
}
Intl.Segmenter 是浏览器内置的分词器,中文按词切,不用自己写正则。它在新版 Chrome、Edge、Firefox、Safari 里都有;如果报 Intl.Segmenter is not a constructor,是浏览器太旧,升级即可。所有文本都用 textContent 写入而不是 innerHTML——摘录内容来自用户输入,用 innerHTML 等于给自己开一个 XSS 口子,卷 8 会专门讲。
第 4 步:js/events.js
export function bindForm(formEl, onSubmit) {
formEl.addEventListener('submit', (event) => {
event.preventDefault();
const data = new FormData(formEl);
const draft = {
title: String(data.get('title') ?? ''),
content: String(data.get('content') ?? ''),
sourceUrl: String(data.get('sourceUrl') ?? ''),
tags: String(data.get('tags') ?? ''),
};
if (!draft.title.trim() || !draft.content.trim()) return;
onSubmit(draft);
formEl.reset();
});
}
export function bindTagBar(barEl, onPick) {
barEl.addEventListener('click', (event) => {
const btn = event.target.closest('button[data-tag]');
if (!btn) return;
onPick(btn.dataset.tag);
});
}
标签栏只有一个监听器,靠 closest 找到被点的按钮——这就是卷 2 讲的事件委托。标签按钮会被整批重建,逐个绑定必然漏绑,委托不受重建影响。
第 5 步:js/main.js
import { loadNotes, saveNotes, createNote, allTags } from './store.js';
import { renderList, renderTagBar, renderStats } from './render.js';
import { bindForm, bindTagBar } from './events.js';
const state = {
notes: loadNotes(),
activeTag: '全部',
};
const listEl = document.querySelector('#note-list');
const tagBarEl = document.querySelector('#tag-bar');
const statsEl = document.querySelector('#stats');
const formEl = document.querySelector('#note-form');
function visibleNotes() {
if (state.activeTag === '全部') return state.notes;
return state.notes.filter((note) => note.tags.includes(state.activeTag));
}
function render() {
const notes = visibleNotes();
renderTagBar(tagBarEl, allTags(state.notes), state.activeTag);
renderStats(statsEl, notes);
renderList(listEl, notes);
}
bindForm(formEl, (draft) => {
state.notes = [createNote(draft), ...state.notes];
saveNotes(state.notes);
render();
});
bindTagBar(tagBarEl, (tag) => {
state.activeTag = tag;
render();
});
render();
main.js 里没有一行 DOM 创建、没有一行 localStorage。它只做三件事:持状态、定规则(筛选)、调别人。 这就是"入口"该有的样子。
第 6 步:改 index.html 并跑通
删掉原来的 <script src="app.js"></script>,换成:
<script type="module" src="./js/main.js"></script>
type="module" 不能少;./ 不能少;.js 扩展名不能少——浏览器不做任何路径猜测。
起服务:
py -m http.server 8000
形如:
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
打开 http://127.0.0.1:8000/,按这张清单逐条过:
| 检查 | 预期 | 不通过说明 |
|---|---|---|
| 页面有样式 | 标题居中、卡片有边框 | styles.css 路径断了 |
| 标签栏显示「全部」 | 一个按钮 | main.js 没执行 |
| 提交一条带两个标签的摘录 | 列表立刻出现、刷新后还在 | store.js 或 saveNotes 没调 |
| 点某个标签 | 只显示该标签的笔记 | 筛选或委托绑错了 |
| 控制台 | 无红字 | 有任何红色先解决它 |
刷新页面数据还在,说明 localStorage 这条路通了。此时把 app.js 删掉——它已经没人引用,留着只会让人下次改错文件:
git rm app.js
git add js index.html
git commit -m "refactor: 把 app.js 拆成 store/render/events/main 四个模块"
3.4.4 三个坑
坑 1:忘了 type="module"
症状:页面白屏,Console 只有一行红字,Network 里 JS 状态是 200。
Uncaught SyntaxError: Cannot use import statement outside a module
成因:普通 <script> 按"经典脚本"解析,import 在这个语境里是非法语句。文件确实下载成功了,是解析阶段就失败。
修法:给标签加上 type="module"。顺带记住它的两个副作用:模块脚本自动 defer(不阻塞 HTML 解析)、自动严格模式。加了 type="module" 之后不能再靠"脚本顺序"传变量,必须走 import。
坑 2:写成了"裸模块名"
症状:
Uncaught TypeError: Failed to resolve module specifier "render".
Relative references must start with either "/", "./", or "../".
成因:写成了 import { renderList } from 'render.js'。浏览器不知道 render.js 在哪——它没有 Node 那套"从 node_modules 里找"的解析规则,只认三种开头:/(站点根)、./(当前目录)、../(上级目录)。这叫"裸模块名",浏览器环境下不合法。
修法:补成 ./render.js。注意扩展名也要写全,./render 同样会 404。第 6 章用 Vite 之后,构建工具会帮你解析裸名(比如 import { useState } from 'react'),但那是工具的功劳,不是浏览器的能力。
坑 3:循环依赖,拿到 undefined
症状:某个函数调用时报 is not a function 或 Cannot access 'xxx' before initialization,但那个函数明明 export 了。
成因:A 依赖 B、B 又依赖 A。浏览器先执行到 A 的 import,转去执行 B,B 又要 A 的值——此时 A 还没初始化完,只能给 undefined 或直接抛暂时性死区错误。报错位置常常在"看起来没问题"的那个文件里,因为真正的环在别处。
修法:先看清环在哪。
npx madge --circular --extensions js js/
形如:
✖ Found 1 circular dependency!
1) render.js > store.js
然后改依赖方向,而不是调 import 顺序:把两边都要用的东西抽到第三个模块(比如 format.js),让 A、B 都只依赖它。如果一时改不动,把"用到时才取"的函数调用从模块顶层挪进函数体内部,也能绕开——但那是止痛药,不是治疗。
本章验收
- 目录里只剩
js/store.js、js/render.js、js/events.js、js/main.js与index.html、styles.css - 能不看代码画出四个模块的 import 箭头,并说出为什么箭头不能反向
- 页面通过
http://127.0.0.1:8000/打开,增删标签、筛选、刷新后数据保留全部正常 - 能解释
file://下模块为什么被拒,并说出报错里的origin 'null'是什么意思 - Console 无红字,Network 里没有任何 404
- 这次重构单独占一条提交,
git show --stat能看到文件的新增与删除
自测
Q1:为什么模块里的顶层 const notes = [] 不会变成 window.notes?这和卷 2 的写法有什么实际差别?
看答案
ESM 规定每个模块有独立的模块作用域,顶层声明只在该模块内可见,不挂到全局对象上。卷 2 的经典脚本里,顶层 `var`/`function` 会成为 `window` 的属性,两个文件同名就互相覆盖;模块化之后同名互不干扰,想共享必须显式 `export` / `import`。副作用是调试时不能在 Console 里直接敲 `notes`,得通过断点或临时挂到 `window` 上。Q2:把 index.html 双击打开,页面结构正常但列表不渲染,Console 报 CORS。为什么"结构正常"?