拆成三个文件,然后撞墙
本合集目录
本章目录
单册说明:本文件是卷 2 的第 7 章,可独立阅读。前置:第 6 章(fetch 与 Promise)。本章把单文件拆成三个文件,并当场撞上 404、MIME、CORS 三类首次报错,一次认清。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 2 · 浏览器三件套(第 7 / 7 章) |
| 前置章节 | 2.6 异步:fetch 与 Promise |
| 本章产出 | index.html + style.css + app.js 三文件版本,用 python -m http.server 跑通 |
| 对应代码 | code/dudao/:三个文件 + notes.json |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 拿到一段红字,能在十秒内判断它是"文件没找到""类型不对"还是"来源不被允许" |
2.7.1 一句话结论:拆文件不是整理房间,是让浏览器分包下载
第 6 章结束时,index.html 里塞着三段东西:<style> 里大约 250 行 CSS,<script> 里大约 200 行 JS,中间夹着 HTML 结构。
现在把它拆成三个文件。这个动作看起来只是"整理",实际上是本卷最容易被低估的一步——因为拆完的一瞬间,页面很可能就坏了一半。
下面是我见过的真实场面。学员按步骤拆完,顺手把三个文件分进了子目录,路径却没跟着改。双击 index.html:页面完全没有样式,数据也没有。控制台两行红字:
GET file:///C:/code/dudao/style.css net::ERR_FILE_NOT_FOUND
Access to fetch at 'file:///C:/code/dudao/notes.json' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, https, data, ...
他做了三件事:把 app.js 改成别的名字、把 style.css 的路径改成绝对路径、在搜索引擎里抄了一段配置。结果一个都没修好,因为他面对的是两个完全不同的问题,而报错里都写着"加载失败"。
拆文件之所以必然撞墙,是因为它引入了本卷前六章从未出现的东西:页面需要主动去"要"另外两个文件。 这个"要"走的是 HTTP 规则,规则里有三道关卡:
| 关卡 | 问题 | 报错关键词 |
|---|---|---|
| 找得到吗 | 路径对不对 | 404 (File not found)、ERR_FILE_NOT_FOUND |
| 是什么类型 | Content-Type 对不对 |
MIME type ('text/html') is not executable |
| 允许我拿吗 | 来源(origin)对不对 | blocked by CORS policy、origin 'null' |
这三类报错在控制台里长得几乎一样,都是一行红字加一个文件名,但修法完全不同:第一类改路径,第二类改服务器或文件,第三类改协议。本章就是把它们拆开。
2.7.2 原理与方法
① 为什么要拆:四个真实收益
| 收益 | 说明 | 什么时候能感受到 |
|---|---|---|
| 缓存 | CSS/JS 独立成文件后,改 HTML 不会让浏览器重下 CSS;改 JS 不会让 CSS 失效 | 第二次访问、部署更新后 |
| 可维护 | 改样式不用在六百行里翻找 <style> 的结束标签 |
第一次改颜色时 |
| 协作 | 两个人分别改 CSS 和 JS,不会在同一段代码上打架 | 有第二个人参与时 |
| 工具支持 | 编辑器的语法高亮、格式化、检查都按文件类型工作;混在一个文件里全是"无效语法"提示 | 打开编辑器就感受到 |
还有一条和本卷直接相关:第 3 章讲的模块化,前提就是"代码在独立文件里"。 卷 3 要用 import/export 把 app.js 拆成几个模块,如果它还嵌在 HTML 里,连第一步都做不了。
② 拆分不是"剪切粘贴",是改连接方式
单文件版里,CSS 和 JS 是内联的:浏览器解析 HTML 时顺手就执行了,不需要额外请求。拆开之后,它们变成外部资源:
<link rel="stylesheet" href="style.css">
<script src="app.js" defer></script>
这两行各自引入了一次新的 HTTP 请求。请求就要遵守 HTTP 的规则,也就会失败。这是"拆完就坏"的根本原因——不是代码坏了,是连接方式变了。
defer 这一行值得单独说。第 5 章我们把 <script> 放在 </body> 前,靠"位置"保证 DOM 已就绪;现在 <script> 移到了 <head>,就必须靠 defer:
| 写法 | 下载 | 执行时机 | 会不会阻塞解析 |
|---|---|---|---|
<script src>(无属性) |
立即,阻塞 | 下载完立刻执行 | 会 |
<script src defer> |
并行下载 | DOM 解析完、按出现顺序执行 | 不会 |
<script src async> |
并行下载 | 下载完立刻执行,顺序不定 | 不会(但执行时可能打断) |
async 适合完全独立的脚本(统计代码),defer 适合要操作 DOM 的业务代码。我们的 app.js 一上来就 querySelector,必须用 defer。 忘了写,就会得到第 5 章那个 Cannot read properties of null。
③ 三类报错的第一现场:看懂控制台
把三类错误各制造一次,控制台会给出这样的三组信息。它们的结构是一样的:谁、做了什么、失败在哪。
| 报错类型 | 真实文本 | 谁在抱怨 | 一眼判断 |
|---|---|---|---|
| 文件不存在 | GET http://127.0.0.1:8000/js/app.js 404 (File not found) |
服务器 | 有状态码 404 |
| 类型不对 | Refused to execute script from 'http://127.0.0.1:8000/app.js' because its MIME type ('text/html') is not executable, and strict MIME type checking is enabled. |
浏览器 | 有 MIME type 和 Refused to |
| 来源不被允许 | Access to fetch at 'file:///C:/code/dudao/notes.json' from origin 'null' has been blocked by CORS policy |
浏览器 | 有 origin 和 CORS policy |
三类问题的排查入口不同:
- 404 去 Network 面板看那条请求的 URL,和你磁盘上的真实文件名逐字符比对;
- MIME 去 Network 面板看那条请求的响应头
Content-Type; - CORS 看报错里的
origin是什么——如果它是null或者file://,说明你根本没起服务。
④ 为什么必须走 HTTP,不能用 file://
file:// 打开页面时,浏览器的"源"(origin)是 null。同源策略规定:源为 null 的页面不能读取其他文件的内容。 这个限制存在的原因很实在——如果没有它,你从网上下载一个 HTML 双击打开,它就能读你硬盘上的任意文件。
不同资源受这条限制的程度不一样:
| 资源 | 在 file:// 下 |
原因 |
|---|---|---|
<link rel="stylesheet"> |
能加载(但受路径限制) | CSS 加载不走 CORS 检查 |
<script src>(普通) |
能加载 | 传统脚本不要求 CORS |
<script type="module"> |
被拦 | 模块加载强制走 CORS |
fetch() / XMLHttpRequest |
被拦 | 读内容,必须过 CORS |
localStorage |
行为不一致 | 各浏览器对 file:// 的源定义不同,Chrome 里同一目录共享 |
这里要澄清一个常见的混淆:type="module" 在 file:// 下被拦,报的是 CORS,不是 MIME。 很多人把这两件事混成一句"模块在本地跑不了",于是去搜 MIME 的修法,怎么改都不对。分野很清楚:CORS 是"你不许拿",MIME 是"你拿到的不是我要的东西"。
卷 3 会用模块化,那时你会再次遇到这条限制。本章的结论只需要记住一句:
只要页面要主动读取别的文件,就必须有 HTTP 服务。
file://只适合"一个文件看效果"。
python -m http.server 提供了这个服务。它把当前目录挂在 8000 端口上,每个文件都能通过 http://127.0.0.1:8000/文件名 访问,源是 http://127.0.0.1:8000,不再有 null 的问题。
2.7.3 动手:拆成三个文件
第一步:建 style.css
新建 style.css,把 index.html 里 <style> 和 </style> 之间的全部内容粘进去,然后删掉这对标签。
第二步:建 app.js
新建 app.js,把 <script> 和 </script> 之间的全部内容粘进去,删掉这对标签。
不要在 app.js 里加 defer、不要加 type,那些是 HTML 的属性,不是 JS 的语法。粘进去的代码第一行应该是 const STORAGE_KEY = ...。
第三步:改写 index.html
把整个 index.html 换成下面这版。注意 <head> 里多了两行,<body> 里的内容一个字都没改。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>读到 · 我的摘录本</title>
<link rel="stylesheet" href="style.css">
<script src="app.js" defer></script>
</head>
<body>
<header class="site-header">
<h1 class="site-title">读到</h1>
<p class="site-sub">把读到的句子留下来,按标签找回去。</p>
</header>
<main class="layout">
<aside class="sidebar" aria-labelledby="tag-title">
<h2 class="sidebar-title" id="tag-title">标签</h2>
<ul class="tag-list" id="tag-list">
<li><button class="tag-btn is-active" type="button" data-tag="">全部</button></li>
<li><button class="tag-btn" type="button" data-tag="认知">认知</button></li>
<li><button class="tag-btn" type="button" data-tag="写作">写作</button></li>
</ul>
</aside>
<section class="content" aria-labelledby="note-title">
<h2 class="section-title" id="note-title">摘录</h2>
<ul class="note-list" id="note-list"></ul>
<p class="empty" id="empty-hint" hidden>还没有摘录。用下面的表单加一条。</p>
</section>
</main>
<section class="stats" aria-labelledby="stats-title">
<h2 class="section-title" id="stats-title">关键词</h2>
<ul class="stats-list" id="stats-list"></ul>
</section>
<section class="composer" aria-labelledby="form-title">
<h2 class="section-title" id="form-title">新增摘录</h2>
<form class="note-form" id="note-form">
<div class="field">
<label for="field-title">标题</label>
<input id="field-title" name="title" type="text" required maxlength="80" placeholder="一句话概括这条摘录">
</div>
<div class="field">
<label for="field-content">正文</label>
<textarea id="field-content" name="content" rows="4" required placeholder="把原文抄进来,或者写一句自己的话"></textarea>
</div>
<div class="field">
<label for="field-source">来源网址</label>
<input id="field-source" name="sourceUrl" type="url" placeholder="https://reading.example/...">
</div>
<div class="field">
<label for="field-tags">标签</label>
<input id="field-tags" name="tags" type="text" placeholder="用空格分隔,例如:认知 写作">
</div>
<button class="primary" type="submit">保存</button>
</form>
</section>
<footer class="site-footer">
<p>读到 · 本地版</p>
</footer>
</body>
</html>
拆完之后,目录长这样:
C:\code\dudao\
├─ index.html 结构
├─ style.css 样式
├─ app.js 逻辑
└─ notes.json 示例数据
第四步:先看它怎么坏
先不要起服务。 直接双击 index.html。
你会看到两种情况之一:样式在、数据没有,或者页面基本正常但示例数据没导入。打开控制台,一定能看到那条 blocked by CORS policy——因为它要 fetch('notes.json')。
这个现象本身就值得记住:CSS 和普通 JS 在 file:// 下能加载,fetch 不能。 所以"页面看起来是好的"给了你一个错误的信号。
第五步:起服务,跑通
cd C:/code/dudao
python -m http.server 8000
打开 http://127.0.0.1:8000/。这一次:
- 样式在(
style.css200); - 三条示例数据在(
notes.json200); - 新增一条,列表立刻更新;
- 切标签,过滤正常;
- 刷新,数据还在。
在 Network 面板里,你应该看到四条请求:/(200)、style.css(200)、app.js(200)、notes.json(200)。把鼠标停在 style.css 上,看响应头:
Content-Type: text/css
停在 app.js 上:
Content-Type: text/javascript
这两个值就是"MIME 类型正确"的样子。记住它们,下一节你要靠它区分第 2 类报错。
这里有一件会让你以为"没跑通"的小事,先说清楚:控制台里可能还有一条 favicon.ico 的 404。
GET http://127.0.0.1:8000/favicon.ico 404 (File not found)
这不是你的代码坏了。浏览器打开任何页面都会自作主张去要一个叫 favicon.ico 的网站图标,你没提供,它就 404。它不影响任何功能。
处理方式有两条,选一条就行:忽略它(推荐,省事且诚实),或者在 <head> 里加一行明确声明"本站没有图标":
<link rel="icon" href="data:,">
data:, 是一个空的 data URL,浏览器拿到它就不再发那个请求。加了之后控制台彻底干净,代价是多一行"看起来像魔法"的代码。本书选择忽略——你要能分辨"哪些红字需要管",这比"控制台一条红字都没有"更重要。
第六步:制造 404,再修好
把 <link rel="stylesheet" href="style.css"> 改成 href="styles.css"(多一个 s),刷新。页面变成无样式的裸 HTML,控制台:
GET http://127.0.0.1:8000/styles.css 404 (File not found)
终端里也会多一行:
127.0.0.1 - - [17/Nov/2026 10:24:31] code 404, message File not found
注意,这里没有 MIME 报错。 python -m http.server 对不存在的文件老实返回 404,不会拿别的东西冒充。改回 style.css,一切恢复。
这一步的价值在于:你亲手确认了"404 是服务器说的,不是浏览器猜的"。以后看到 404,直接去服务器目录里对文件名,不用怀疑代码。
2.7.4 三个坑
坑 1:404 —— 路径错,而你以为是代码错
症状:页面没有样式,或者点击完全没反应。控制台:GET http://127.0.0.1:8000/js/app.js 404 (File not found)。文件明明就在,你甚至能双击打开它。
成因:三种,按出现频率排——① 相对路径算错了:app.js 在根目录,你写了 js/app.js;② 大小写不一致:Windows 文件系统不区分大小写,App.js 能找到 app.js,但部署到 Linux 服务器立刻 404(卷 7 会真实遇到);③ 文件其实叫 app.js.txt,Windows 默认隐藏已知扩展名,你看到的 app.js 是全名的一部分。
修法:不要靠眼睛看,去 Network 面板点那条 404 的请求,看它请求的完整 URL,再和终端里 ls 出来的真实文件名逐字符比。Windows 上先在资源管理器里勾选"文件扩展名",再做对比。大小写这条要养成习惯:写路径永远和真实文件名完全一致。
坑 2:MIME —— 文件找到了,但类型不对
症状:控制台里 Refused to apply style from '...' because its MIME type ('text/html') is not a supported stylesheet MIME type,或者 Refused to execute script ... because its MIME type ('text/html') is not executable。文件存在,路径也对。
成因:服务器返回了这个文件,但响应头里的 Content-Type 是 text/html。最常见的原因是服务器的"回落"配置:请求的文件不存在时,它不返回 404,而是返回 index.html(很多开发服务器和 SPA 部署都这么配)。浏览器拿到一个 HTML 页面,却被要求"当成 CSS 用",于是拒绝执行。另一种成因是文件扩展名被改过,比如把一段 HTML 存成了 style.css。
修法:去 Network 面板看那条请求的状态码和 Content-Type。如果状态码是 200 但类型是 text/html,说明服务器给错了文件——检查是不是路径落到了回落规则里,或者服务器把 .css 映射错了。这一类错误与"代码写错"无关,不要改 JS。
顺带澄清本章开头那个混淆:<script type="module" src="app.js"> 在 file:// 下报的是 CORS(origin 'null'),不是 MIME。MIME 报错的前提是"已经通过 HTTP 拿到了响应,只是类型不对"。
坑 3:CORS —— 从 file:// 打开了页面
症状:Access to fetch at 'file:///C:/code/dudao/notes.json' from origin 'null' has been blocked by CORS policy。页面可能还有样式,所以你不觉得是"没起服务"。
成因:file:// 页面的源是 null。同源策略不允许 null 源去读取其他文件。fetch 要过这道检查,所以必失败。如果脚本写的是 <script type="module">,报错对象会换成脚本,文本变成 Access to script at 'file:///.../app.js' from origin 'null' has been blocked by CORS policy,本质完全一样——模块加载强制走 CORS 检查,而普通 <script src> 不走。
修法:起一个 HTTP 服务,用 http://127.0.0.1:8000/ 打开,不要双击文件。不要去搜"关闭浏览器安全策略""加 --allow-file-access-from-files 启动参数"——那会让你的浏览器对所有本地文件敞开,而且团队里别人的机器上依然跑不通。换协议,不换安全设置。
本章验收
- 目录下只有
index.html、style.css、app.js、notes.json四个文件,没有残留的内联<style>/<script> - 双击
index.html能复现origin 'null'的 CORS 报错 -
python -m http.server 8000后,Network 面板里四条请求全部 200 -
style.css的Content-Type是text/css,app.js是text/javascript - 故意把路径写错能复现 404,改回后恢复
- 能不看笔记说出 404 / MIME / CORS 各自的排查入口
自测
Q1:<script src="app.js" defer> 和把 <script src="app.js"> 放在 </body> 前,效果一样吗?
看答案
对这个项目来说,两者都能保证脚本执行时 DOM 已就绪,所以都能跑。差别在细节:`defer` 的脚本是**并行下载**的,不阻塞 HTML 解析,而且多个 `defer` 脚本按出现顺序执行;放在 `` 前的脚本要等 HTML 解析到那一行才开始下载(虽然现代浏览器有预扫描优化)。拆成多文件后,`defer` 更稳、更明确,所以本书改用 `defer`。注意 `async` 不同:它下载完就执行,顺序不定,不能用于有依赖关系的脚本。Q2:控制台同时出现 404 和 MIME type ('text/html') 两条报错,可能是什么情况?
看答案
常见于"服务器把所有未匹配路径回落到 `index.html`"的配置。浏览器请求 `style.css`,服务器没找到,返回 `index.html` 的内容并带上 200 和 `text/html`——这时只有 MIME 报错没有 404。如果同时看到 404 和 MIME,通常是两个不同资源各自出错:一个真 404,另一个被回落成了 HTML。排查时按 URL 逐条对,不要当成一个问题。Q3:为什么 python -m http.server 下把 CSS 路径写错只会得到 404,而不是 MIME 报错?
看答案
因为它的行为很"老实":文件不存在就返回 404 和一个纯文本错误页,不会拿 `index.html` 顶替。MIME 报错需要"服务器返回了一个 200 响应,但内容是 HTML"这个条件,`http.server` 不制造这个条件。所以你在这套环境里练 404 最方便,而 MIME 的现场要到带回落规则的服务器上才会遇到。理解这个差别,才能判断"我这次是真找不到文件,还是拿到了错的文件"。下一步
三个文件跑通了,但它们还是"三个孤立的文件":没有版本管理,改坏了回不去;没有依赖管理,想引入工具就只能手工下载。卷 3 从 Git 的心智模型开始,把这份代码变成一个能回溯、能构建的工程。