HTML文件名须全小写+kebab-case（如about-us.html），首页必须为index.html；多页项目应统一置于pages/目录，资源引用用根相对路径（/css/main.css）；class/id命名需语义化（btn-primary而非red-btn），data-*属性须加项目前缀并用kebab-case。
HTML文件名必须全小写 + kebab-case，否则部署就404
Linux/Nginx/Apache 服务器默认区分大小写，Index.html 或 UserProfile.html 在多数生产环境里等同于不存在；GitHub Pages 和部分旧版 IIS 对下划线路径（如 user_profile.html）解析异常，本地双击能打开，一上传就返回 404 Not Found，控制台还看不出明显线索。
实操建议：
- 只用小写字母、数字、短横线（
-），单词间严格用-连接：例如about-us.html、blog-post-2024.html - 数字可出现在中间或末尾，但不能开头：
2024-report.html❌，report-2024.html✅ - 首页必须是
index.html，不是home.html或Index.html—— Web 服务器索引列表中只有index.html是默认且大小写敏感的匹配项 - Windows 用户务必在文件夹选项中开启「显示文件扩展名」，避免保存成
index.html.txt；VS Code 保存时选「All Files」，Sublime Text 保存后右键查属性确认类型
多页面项目该把 HTML 文件放哪：pages/ 目录不是可选项
超过 5 个页面、需复用页头页脚、靠纯静态方式维护的中大型项目，pages/ 是最轻量又可靠的组织方式。不这么做，改一个导航就要手动同步二十个文件；加个新页面还得反复检查路径拼错没。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
-
pages/about.html里写<script src="js/main.js"></script>→ 浏览器实际请求的是pages/js/main.js，而不是你放在根目录下的那个 - 用
../css/main.css这类相对路径 →pages/about.html和blog/post.html的上溯层数不同，一处改对，另一处就断
正确做法：
- 所有 HTML 统一放
pages/下：pages/about-us.html、pages/contact-us.html - 资源引用全部用根相对路径：
<link rel="stylesheet" href="/css/main.css">、<script src="/js/main.js"></script> -
pages/本身不嵌套子目录；若需分组（如博客），用pages/blog/intro.html，而非pages/blog/intro/index.html—— 后者增加一层路由配置成本，且无构建工具时易出路径错
class 和 id 命名别碰“red”“left”“div1”，半年后你自己都懵
这类命名不是懒，是埋雷：red-btn 一旦设计师把主色改成橙色，这个 class 就彻底失效；left-nav 如果某天布局变成顶部折叠菜单，语义就崩了；div1 或 section-a 让新人根本猜不出它管哪块逻辑。
实操建议：
- 用功能或意图命名，而非外观或位置：
btn-primary而非red-btn，sidebar-nav而非left-nav -
id必须唯一且稳定，适合锚点或 JS 操作：id="contact-form"✅，id="form1"❌ - 若用 BEM，严格按
block__element--modifier格式：card__title--large，不混用下划线或驼峰 - 避免纯数字或泛用前缀：
my-div、section-2都不可维护
data-* 属性必须加项目前缀，不然 Alpine.js 或 HTMX 会抢你的事件
浏览器不校验 data- 属性，但第三方库（比如 Alpine.js 的 data-toggle、HTMX 的 data-hx-get）会监听同名属性。没加前缀，等于把自己的开关暴露给所有插件。
实操建议：
- 加简短但明确的项目/模块前缀：
data-myapp-modal-target、data-shop-cart-item-id - 前缀后仍用 kebab-case：
data-abc_user_id❌，data-abc-user-id✅ - 值尽量保持简单类型（字符串、数字），避免 JSON 字符串嵌套；需要复杂数据时改用
<script type="application/json">块 - 绝对不要用
data-存 token、邮箱等敏感信息 —— 它在 HTML 源码里完全可见
最容易被忽略的一点：路径和命名不是为了“看起来整齐”，而是为了“改起来不崩溃”。一个 - 写成 _，一次 ../ 没算准层级，都可能让整个页面在部署后白屏——而错误提示往往只在控制台里闪一下，连日志都不留。
