HTML文件命名规范与技巧分享

HTML文件命名看似微小，实则关乎网站能否稳定上线、跨平台兼容及团队协作效率——必须严格采用全小写+短横线（kebab-case）格式，禁用下划线、驼峰、空格、中文、emoji及大小写混用；首页统一为小写的index.html，多单词名用语义化短横分隔（如user-profile.html），避免序号依赖；否则在GitHub Pages、旧版IIS、Nginx/Apache等环境中极易触发404、路由失效或编码乱码。真正棘手的不是规则本身，而是习惯差异，推荐通过ESLint插件实现提交前自动校验，让规范落地不靠自觉而靠机制。

HTML 文件名不是随便起个名字就行，错用下划线、大小写混用、带空格或中文，部署到 GitHub Pages 或旧版 IIS 时大概率直接 404。

为什么 user_profile.html 在 GitHub Pages 上打不开

GitHub Pages 默认使用 Jekyll 构建，而 Jekyll 会忽略所有以下划线开头的文件和目录（如 _config.yml），但更关键的是：很多静态托管服务（包括部分 Nginx/Apache 配置）对下划线路径不作标准化处理，导致 URL 解析失败。浏览器请求 /user_profile.html，服务器可能返回 404 而不是重定向或容错响应。

• 旧版 Windows IIS 会把 user_profile.html 当成非法路径字符组合，拒绝服务
• userProfile.html 在 Linux 服务器上可能因大小写敏感被当成另一个文件（userprofile.html 才是真实文件）
• URL 中出现空格会自动编码为 %20，既难读又易在复制粘贴时出错

index.html 必须小写且不能写成 Index.html 或 home.html

绝大多数 Web 服务器（Nginx、Apache、Vercel、Netlify）默认只识别小写的 index.html 作为目录索引文件。哪怕你的本地开发环境能打开 Index.html，上线后大概率首页空白或跳转失败。

• Apache 的 DirectoryIndex 指令默认只列 index.html，不包含 Index.html
• GitHub Pages 的静态路由逻辑严格匹配小写文件名，Home.html 不会被当作入口
• 如果项目有多个入口（如管理后台），用 admin/index.html，而不是 admin.html —— 后者语义模糊、无法嵌套路由

多单词文件名该用 - 还是 _？

必须用短横线（kebab-case），这是唯一被全平台广泛兼容的分隔方式。下划线在 URL 中容易被浏览器渲染为下划线样式（尤其在未加样式的纯文本链接中），且部分 CDN 或代理层会静默过滤含下划线的路径段。

• ✅ 正确：faq-section.html、user-profile.html、product-listing.html
• ❌ 错误：faq_section.html（下划线）、userProfile.html（驼峰）、user profile.html（空格）
• 数字补零仅在排序必要时才用：blog-post-01.html，但更推荐语义化命名如 blog-intro-to-html.html，避免序号维护成本

文件名里能用中文或 emoji 吗

绝对不能。中文文件名在 URL 中会被编码为一长串 %E4%BD%A0%E5%A5%BD，不仅难以记忆、不利于 SEO，还会在某些邮件客户端、命令行工具或旧版 FTP 客户端中触发乱码或截断。

• Windows 命令行（cmd/PowerShell）对 UTF-8 文件名支持不稳定，你好.html 可能显示为乱码，del 命令无法识别
• Git 在不同系统间同步时，中文文件名可能产生编码冲突（如 Windows 的 GBK vs macOS 的 UTF-8）
• emoji 是 Unicode 字符，部分 CDN 缓存策略会拒绝缓存含 emoji 的 URL，导致加载变慢或失败

最麻烦的不是命名本身，而是团队成员各自习惯不同：有人坚持 snake_case，有人随手大写首字母，结果合并代码时发现同一页面在不同人本地是两个文件。统一用 ESLint + file-name-casing 插件做 pre-commit 校验，比靠嘴说管用得多。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《HTML文件命名规范与技巧分享》文章吧，也可关注golang学习网公众号了解相关技术文章。