HTML中文件目录结构组织的最佳实践与命名规范建议-html教程-PHP中文网

小项目直接根目录起步最稳：index.html放根目录，css/、js/、images/平铺，用相对路径；中大型项目必须分src（源码）和dist（构建产物），html资源引用用根相对路径，命名用kebab-case和语义化class。

html中文件目录结构组织的最佳实践与命名规范建议

小项目别硬套中大型结构，否则路径错一次，本地双击打开就白屏；中大型项目不拆 src 和 dist，后期改个颜色变量都要手动同步三处。

单人维护、≤5 个页面、不用构建工具的静态站，直接根目录起步最稳。不是“看起来整齐”才分目录，是“不这么放就容易出错”才必须分。

index.html 必须放在根目录——所有服务器默认找它，挪到 pages/ 里就得配重定向，本地双击打开直接 404
css/ 下只放 main.css 和 reset.css，别建 css/base/ 或 css/v2/——没构建工具时，每多一层就是一次相对路径计算失误点
js/ 里只存 main.js 和 utils.js，避免 js/lib/dom.js 这类嵌套——pages/about.html 里写 <script src="js/main.js"></script> 会去查 pages/js/main.js，而不是你预期的根目录那个
images/ 可分 icons/、banner/，但别超过两层，比如 images/icons/social/twitter.svg 已经难定位、难迁移
所有内部链接用相对路径：pages/contact.html，不是 /pages/contact.html——后者在本地双击打开时触发浏览器安全策略，直接 404

一旦开始用 Sass、ES6 模块或 Vite 构建，源码和上线文件混在一起就是定时炸弹：本地跑得通，构建后 CSS 路径全错；别人接手第一件事是删掉整个目录重来。

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

src/ 存所有可编辑源码：src/html/（含 index.njk）、src/css/scss/（main.scss）、src/js/modules/（nav.js）
dist/ 是构建产物，只含最终能上线的文件：index.html、css/main.css、js/main.js，禁止手动修改
public/ 存不参与构建的静态资源：public/favicon.ico、public/robots.txt，构建时原样复制进 dist/，别丢进 src/ 里——Webpack/Vite 默认不处理 src/ 下的非源码文件
HTML 中所有资源引用必须用根相对路径：<link rel="stylesheet" href="/css/main.css">，不是 ../css/main.css——前者以域名根为基准，后者依赖当前 HTML 文件位置，pages/about.html 和 blog/post.html 的 .. 层数不同，极易断裂

命名不是为了好看，是为了半年后你自己改起来不崩溃。拼错一个字母、缩写一个单词，三个月后都可能找不到源头。

文件名必须用 kebab-case：user-profile.html，不能用 user_profile.html 或 UserProfile.html——GitHub Pages、部分 IIS 服务器对下划线响应异常，导致 404
class 名禁用纯样式描述：red-text、float-left，优先用业务语义：error-message、product-card；BEM 推荐显式表达层级：nav__link--active，而非 nav-link-active
id 必须唯一且稳定，适合锚点或 JS 精确操作：id="contact-form"，不是 id="form1"；避免 div1、section-a 这类泛用名
data-* 属性必须加项目前缀：data-shop-cart-item-id，不能只写 data-toggle——Alpine.js、HTMX 都可能监听同名属性，不加前缀极易冲突

不能。浏览器原生不支持组件导入，components/header/header.html 放着不动，它就只是个文件，不会自动拼进页面里。

若不用构建工具，可用服务端包含（如 PHP include）或服务器支持的 <include></include> 注入，但需后端配合
纯前端静态页想复用，推荐用 FastHTML 或类似框架封装函数：header_template() 比维护一堆 HTML 片段更可控
警惕过早抽象：一个只有 <nav><ul></ul></nav> 的 nav.html，不如直接写在 index.html 里——抽象成本高于收益
每个组件子目录应含同名 HTML、CSS、JS：components/header/header.html、components/header/header.css、components/header/header.js，否则维护时根本不知道样式在哪、逻辑在哪