跳到正文
零到全栈 · 卷 3 · 工程化与版本控制

从脚本到模块

本合集目录
本章目录

单册说明:本文件是卷 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。为什么"结构正常"?

看答案 因为 HTML 和 CSS 走的是普通资源加载,`file://` 下允许;被拦的是 `