HTML文件名必须用全小写+kebab-case，禁用下划线、大写、空格、中文及特殊符号；首页统一为index.html；class和id命名同样须用kebab-case且语义化，避免样式化或泛用名。
HTML文件名必须用小写 + kebab-case
大小写混用或大写开头在 Linux/Nginx/Apache 等区分大小写的服务器上会直接 404；下划线（user_profile.html）在 GitHub Pages、旧版 IIS 或某些 CDN 配置下也会触发路径解析失败。真实错误现象是：本地双击能打开，部署后返回 404 Not Found，但控制台看不出明显线索。
正确做法只有一条路：index.html、about-us.html、user-profile-page.html —— 全小写，单词间用短横线（-），不带空格、中文、点号、括号或特殊符号。
- 别写
AboutUs.html、user_profile.html、contact us.html - 数字可出现在中间或末尾，但不能开头：
2024-report.html❌，report-2024.html✅ - 多级目录也一样处理：
/blog/tech-intro.html，不是/Blog/TechIntro.html
扩展名只能选 .html 或 .htm，优先 .html
.htm 是早期 DOS 系统 8.3 命名限制的遗留，现在几乎无必要。但若你遇到老旧 CMS 或内部工具强制要求 .htm，得按它来——否则可能被自动重写或拦截。
关键陷阱在于 Windows 默认隐藏扩展名。你“以为”保存的是 index.html，实际可能是 index.html.txt，浏览器打开就变成下载或乱码。务必在文件夹选项中开启「显示文件扩展名」，并手动确认后缀完整。
立即学习“前端免费学习笔记（深入）”；
- VS Code 保存时，在「另存为」对话框底部选择「All Files」而非「Text File」
- Sublime Text 保存后右键 →「属性」→ 查看「文件类型」是否为「HTML Document」
- Mac 上用
file index.html终端命令验证类型，输出含「HTML document text」才对
首页必须叫 index.html，不能是 home.html 或 Index.html
Web 服务器（Nginx、Apache、Vercel、Cloudflare Pages）默认查找的索引文件列表里，index.html 排第一且大小写敏感。Index.html 在多数 Linux 服务器上等同于不存在；home.html 则完全不会被自动匹配，用户访问域名时 404。
如果你用构建工具（如 Vite、Next.js）或静态站点生成器（Hugo、Jekyll），它们通常会把入口 HTML 自动设为 index.html，但手写项目极易忽略这点。检查方式很简单：删掉当前 index.html，放一个空的 home.html，然后访问 http://localhost:5173/ —— 如果没内容，说明服务器根本没加载它。
- 子目录也遵循同样规则：
/admin/index.html是example.com/admin/的入口 - 不要靠重定向补救，那只是掩盖问题，且增加首屏延迟
- CI/CD 流水线中，确保打包产物根目录下存在且仅有一个
index.html
class 和 id 名称也要用 kebab-case，且禁用样式化命名
很多人以为只有文件名要规范，其实 class 和 id 写错一样引发维护灾难。比如 class="red-btn" 换主题后按钮变橙色，这个 class 就彻底失效；id="left-nav" 在响应式布局里 nav 可能跑到右边，语义瞬间崩塌。
更隐蔽的问题是 JS 获取失败：document.getElementById("user.email") 会报错，因为点号（.）在 CSS 选择器语法中是类分隔符，必须写成 document.getElementById("user\.email") —— 这种转义没人记得住，也不该让前端工程师去猜。
- 统一用
kebab-case：class="main-header"、id="search-form" - 避免纯数字或泛用名：
id="1"、class="div2"无法定位、不可读、易冲突 - BEM 模式下严格用双下划线和双短横：
card__title--large，不是card-title-large
最常被跳过的细节是：文件名、class、id、data-* 属性三者命名风格必须统一。一旦混用 snake_case 和 kebab-case，CSS 选择器、JS 查询、自动化脚本都会开始出哑巴错——不是报错，而是查不到、不生效、难调试。
