跳到正文
零到全栈 · 卷 2 · 浏览器三件套

拆成三个文件,然后撞墙

本合集目录
本章目录

单册说明:本文件是卷 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/。这一次:

  1. 样式在(style.css 200);
  2. 三条示例数据在(notes.json 200);
  3. 新增一条,列表立刻更新;
  4. 切标签,过滤正常;
  5. 刷新,数据还在。

在 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 的心智模型开始,把这份代码变成一个能回溯、能构建的工程。

→ 卷3-01-Git的心智模型.md