A02 搭建编写环境

摘要：HTML 的编写环境由编辑器、文件目录、浏览器预览三部分组成。手工维护这三者的同步容易出错，常见问题是改完不生效、文件存成 .txt、图片路径失效。本文给出一套最小可用环境：一个编辑器、一个固定目录、两种预览方式，并用本地服务器替代双击打开，避免路径与缓存干扰。
关键词：编辑器，本地服务器，文件目录，预览，缓存

所属：frontend/html / A-入门 ｜上一篇：A01-认识网页与HTML ｜下一篇：A03-写出第一个页面

1 引言

记事本能写出正确的 HTML，这一点在 A01 已经验证。问题出现在第二个文件：目录开始分散、文件名开始重复、改完刷新看不到变化。这些现象多数与环境有关，与代码无关。

本文解决两件事：固定一套目录与文件命名方式，把「双击打开」换成「本地服务器预览」。范围见表 1-1。

项	本文覆盖	本文不覆盖
编辑器	VS Code 的安装与四项必要设置	插件生态、快捷键体系、主题定制
预览方式	本地服务器、浏览器强刷、开发者工具	线上部署、域名与 HTTPS
目录	单科目单目录的固定结构	多项目工程化、构建工具链

2 预备知识

项	要求	核对方式
操作系统	Windows 10+ / macOS 12+	—
编辑器	VS Code 1.95 及以上	菜单「帮助 → 关于」查看版本
浏览器	Chrome 130+ / Edge 130+	地址栏 `about:version`
可选工具	Node 20+ 或 Python 3.10+	终端执行 `node -v` 或 `python -V`
前置篇目	A01 认识网页与 HTML	需要理解 HTML 文件的基本结构

3 原理与实现

3.1 三个角色与一条同步线

编辑器、磁盘、浏览器是三个独立角色，之间只有「保存」与「刷新」两次同步，如图 3-1 所示。

flowchart LR
    A["编辑器<br/>内存中的文本"] -->|"保存 Ctrl+S"| B["磁盘<br/>index.html"]
    B -->|"浏览器读取"| C["浏览器<br/>解析并渲染"]
    C -->|"修改后按 F5"| B

图 3-1 编辑、保存、刷新之间的同步关系

图上可见：页面不更新只有两种可能——文本没写到磁盘（未保存），或浏览器没重新读取（缓存未刷新）。

这条链路决定了排查顺序：先确认文件保存时间戳，再确认浏览器是否强刷，最后才怀疑代码。

3.2 安装与最小配置

安装 VS Code 后只需四项设置，全部在「设置」中搜索关键字完成，见表 3-1。

设置项	值	作用
`files.autoSave`	`afterDelay`	停止输入 1 秒自动保存，消除漏保存
`files.eol`	`\n`	统一换行符，避免提交时整文件 diff
`files.encoding`	`utf8`	与 `meta charset` 保持一致
`editor.tabSize`	`2`	与 HTML 缩进习惯一致

三种预览方式的能力差异见表 3-2，本篇采用本地服务器。

方式	命令 / 操作	地址示例	限制
双击文件	资源管理器双击 `.html`	`file:///D:/html/index.html`	部分脚本与请求能力被浏览器禁用
本地服务器（Node）	`npx serve .`	`http://localhost:3000`	需要 Node，首次会下载包
本地服务器（Python）	`python -m http.server 8000`	`http://localhost:8000`	需要 Python

统一目录结构如下，科目内所有练习都放在 html-practice 下：

html-practice/
├─ index.html
├─ about.html
└─ assets/
   ├─ images/
   └─ styles/

目录规则三条：文件名只用小写英文与连字符；主文件固定命名 index.html；静态资源统一放 assets，不散落在根目录。

4 验证与讨论

按以下五步操作，结果与表 4-1 对照。

新建目录 html-practice，在其中新建 index.html，写入 A01 的示例代码。
在该目录打开终端，执行 npx serve .；无 Node 环境时执行 python -m http.server 8000。
浏览器访问终端输出的地址，页面正常显示即成功。
修改 h1 文字并保存，观察页面是否自动刷新；无自动刷新时按 F5。
按 F12 打开开发者工具，切到 Console 面板，确认没有红色报错。

检查项	预期结果	不通过时先看
访问协议	`http://localhost` 开头	表 3-2 命令是否执行
页面标题	显示 `index.html` 内容	目录是否为当前目录
保存后刷新	文字内容同步变化	表 3-1 自动保存设置
Console 面板	无红色报错	表 5-1 第一行

讨论与局限。 本地服务器每次重启端口可能变化，固定端口需显式指定（npx serve -l 3000 .）。另外本篇未引入任何构建工具，文件改动即生效；一旦后续引入打包器，这个「保存即刷新」的模型会失效，需要改用开发服务器。

5 常见问题

现象	原因	处理
`localhost` 拒绝连接	服务器未启动，或终端已退出	回到目录重新执行表 3-2 的命令
端口被占用报错	默认端口已有其它进程	换端口，如 `npx serve -l 3001 .`
页面仍是旧内容	浏览器缓存	`Ctrl + F5` 强刷，或在开发者工具勾选禁用缓存
中文显示为乱码	文件编码不是 UTF-8 或缺少 charset 声明	编辑器右下角切 UTF-8，检查 `meta charset`
文件出现在目录但打不开	后缀被资源管理器隐藏，实为 `.txt`	打开「显示文件扩展名」后重命名

6 结论

序号	结论	依据
1	编辑器只负责文本，页面更新依赖保存与刷新	图 3-1
2	本地服务器预览优于双击，路径与请求行为一致	表 3-2
3	编码、缩进、换行三项设置一次配好，长期受益	表 3-1
4	目录与命名先固定，后续篇目直接复用	3.2 节目录结构

参考文献

[1] Visual Studio Code · Settings，Microsoft，https://code.visualstudio.com/docs/getstarted/settings（访问于 2026-10-29）
[2] serve，Vercel，https://github.com/vercel/serve（访问于 2026-10-29）
[3] HTTP 服务器（http.server），Python 文档，https://docs.python.org/zh-cn/3/library/http.server.html（访问于 2026-10-29）