</>HTML → WordPress ASSETS GUIDE
v1.2.0 README GitHub ↗
工程实践 · 可复制代码 · 常见问题

前端资源管理
快速参考工作台

从第一个 HTML 页面，到多页面复用，再到 WordPress 经典主题。把 CSS / JavaScript 的放置、加载、依赖和验收变成可以重复使用的规范。

查看 WP 核心代码 →上线检查清单
记住一句话：单页分离，多页复用，组件按需，WordPress 统一加载。

支持在当前页面定位关键词，按 Enter 跳转到第一个匹配模块。

START

三个阶段，一条开发路线

STAGE 01

单页面 HTML

先把结构、样式和脚本分离；不必过早设计复杂目录。

style.css + main.js打开运行示例 ↗
STAGE 02

多页面 HTML

公共样式和逻辑复用，页面专属 CSS / JS 按需加载。

common.* + pages/*打开运行示例 ↗
STAGE 03

WordPress 主题

尽量保留 CSS / JS 代码，把资源加载交给 enqueue 管理。

inc/enqueue.php查看主题源码 ↗

阶段 02 和阶段 03 使用相同的 CSS / JS 文件；差异主要在页面模板和加载机制。WordPress PHP 模板不能通过静态 GitHub Pages 直接运行。

02

目录结构：从少到多，不提前复杂化

单页面

project/
├── index.html
└── assets/
    ├── css/style.css
    └── js/main.js

多页面 / 主题资源

assets/
├── css/
│   ├── common.css
│   └── pages/
│       ├── home.css
│       ├── products.css
│       └── contact.css
└── js/
    ├── common.js
    └── pages/
        ├── home.js
        ├── products.js
        └── contact.js

# 未来使用第三方库时可增加：
assets/vendor/
└── swiper/
什么时候拆分？当两页共享同一套功能，就考虑放入 common.*；只有某一页需要的逻辑，留在 pages/*。不存在的功能不必创建空文件。assets/vendor/ 是未来可选目录，并非当前仓库已有资源。
03

CSS / JavaScript 加载规则

方式主要行为推荐用途
<link rel="stylesheet">加载样式表，可能阻塞渲染主要 CSS 文件
<script defer>经典脚本下载可并行，解析完成后按文档顺序执行常规独立文件默认优先
<script async>就绪后执行，不保证与其他脚本的顺序无顺序依赖的独立脚本
<script type="module">模块支持 import，默认延后执行ES Modules 项目
wp_enqueue_script()WordPress 统一处理依赖、版本及加载位置/策略WordPress 经典主题
HTML · 推荐的基础引入
<head>
  <link rel="stylesheet" href="assets/css/common.css">
  <link rel="stylesheet" href="assets/css/pages/home.css">
  <script src="assets/js/common.js" defer></script>
  <script src="assets/js/pages/home.js" defer></script>
</head>
注意：defer 的顺序保证适用于普通经典外部脚本；混合 async、module、动态注入、优化插件时应重新核对执行关系。多个依赖应显式声明，而非依靠偶然顺序。优化插件可能改写脚本输出，务必在启用优化后验证实际执行顺序。
04

页面资源矩阵：每个页面究竟加载什么？

页面全站公共资源页面专属资源
Homecommon.css / common.jshome.css / home.js
Aboutcommon.css / common.js不需要
Productscommon.css / common.jsproducts.css / products.js
Contactcommon.css / common.jscontact.css / contact.js

这是仓库现有多页面示例的资源关系，不是要求所有真实网站都使用这四类页面。页面数量和内容类型变化时，应根据实际职责调整。

05

WordPress enqueue：核心代码速查

将资源集中到 inc/enqueue.php，由 functions.php 引入。下方代码摘自仓库演示并经过局部裁剪；切换标签查看各类写法。以下使用 strategy 的示例要求 WordPress 6.3+；旧版第五参数 true 只代表页脚加载，并不等于 defer。

公共资源 · 每个前台页面
关键理解：handle 是资源唯一句柄；deps 声明依赖；版本号用于缓存管理。wp_enqueue_style() 的可选第 5 参数 $media 默认是 all，按需可用 screen 或 print。演示项目使用 filemtime()，生产环境可以采用发布版本或构建哈希。get_theme_file_uri() / get_theme_file_path() 会优先查找子主题文件，缺失时回退父主题；两者应配套使用。

上述固定 slug 判断只用于教学。真实多语言网站可以根据模板、is_page_template()、内容类型或可靠的业务条件改造。enqueue 的句柄去重并不会自动识别两个不同 URL 是否指向同一个库。

查看完整、可运行的 enqueue.php 源码 ↗
06

第三方库：明确版本和依赖

一处管理

不在多个 PHP 模板或页头页脚重复写同一个库的 URL。

版本明确

记录外部库实际版本；升级之前先验证兼容性。

先依赖，后初始化

例如使用 Swiper 的页面脚本要等 Swiper 库就绪后再执行。

页面按需

并非所有页面都需要轮播、弹窗或动画脚本。

WordPress · 第三方依赖示意（非仓库已实现功能）
// 前提：已安装对应版本的 Swiper 文件；在 wp_enqueue_scripts 回调内执行。
wp_register_script(
    'my-swiper',
    get_theme_file_uri('assets/vendor/swiper/swiper-bundle.min.js'),
    [],
    '11.x', // 示例值：替换为实际安装版本
    ['in_footer' => true, 'strategy' => 'defer']
);
wp_enqueue_script('my-swiper');
wp_enqueue_script(
    'site-slider',
    get_theme_file_uri('assets/js/pages/slider.js'),
    ['my-swiper'],
    '1.0.0',
    ['in_footer' => true, 'strategy' => 'defer']
);
边界：当前仓库的运行示例不包含 jQuery、Bootstrap、Swiper 或 Fancybox；这里仅介绍管理原则，示意代码需要先放置真实的第三方文件及 slider.js，并将示例版本号替换为真实版本；当前仓库没有这些文件。直接 enqueue 并提供完整参数也合法，register 不是每次必需。
07

常见问题：从现象倒查原因

30 秒排查顺序：① Network 中资源是否返回 200？→ ② Console 报错属于“未定义 / null / 不是函数”哪类？→ ③ 检查 DOM、依赖及加载顺序 → ④ 关闭优化特性作对照测试 → ⑤ 清除浏览器、WP 和 CDN 缓存后复测。
诊断优先于盲目添加 !important 或反复改脚本。
修改 CSS 后，页面为什么还是旧样式？
先到 DevTools → Network 确认实际请求的 CSS URL 和响应内容，再检查浏览器缓存、资源版本、WordPress 优化插件以及 CDN 缓存。不要立即通过增加 !important 来掩盖问题。
控制台出现 xxx is not a function？
查看插件或依赖库是否加载成功、是否重复引入不同版本、初始化脚本是否执行太早。再检查脚本合并、延迟执行或缓存插件是否改变了实际顺序。
出现 Cannot read properties of null (reading 'addEventListener')？
确认选择器在当前页面能找到元素；为可选组件增加存在性检查，并在 DOM 就绪后初始化。如果脚本在多个页面共用，要特别注意其中一些页面不存在对应元素。
为什么 About 页面无需请求页面专属 JS？
当前仓库的 About 页面没有对应的独立交互功能，公共脚本已经足够。不要为了目录对称而加载空脚本，或为了省事让所有页面加载所有脚本。
管理员正常、游客异常，排查顺序是什么？
分别使用登录和退出状态打开 DevTools，比较脚本请求、响应、加载顺序与控制台报错，再检查缓存和优化配置。两种身份可能命中不同的缓存或优化路径。
怎样确认 WordPress 条件加载真正生效？
打开 Home / About / Products / Contact，Network 分别筛选 CSS 和 JS。检查公共资源每页都有、专属文件只出现在对应页面、没有 404 或重复请求。再验证页面交互与移动端行为。
WP Rocket / Cloudflare 等优化后，为什么脚本突然异常？
先在 Network 核实最终脚本 URL 与顺序；针对 JS 延迟执行、合并和排除规则逐项对照，而不是一次全部更改。确认是否有缓存旧版本、登录和游客优化路径不同等情况。修复后重新启用优化项并回归测试。
文件修改了，但 filemtime() 生成的版本仍不变？
确认主题文件真实路径、服务器部署是否保留了修改时间、文件系统时间与 PHP 文件状态缓存；必要时再检查 OPcache/应用及 CDN 缓存。生产环境优先采用发布版本或构建哈希；不能把问题一概归咎于 OPcache。
08

发布前检查清单

按当前项目逐项勾选。本设备浏览器会保存勾选状态；切换项目时建议重置。

0 / 12 已完成

现代构建工具（Vite / Webpack）可以通过构建产物及 manifest 接入 WordPress，但不属于本仓库当前三阶段演示范围。

规范不是为了多写代码，而是为了少踩坑。

遇到更复杂的业务需求，优先回看真实源码与验收文档，确认当前模式是否适用，再决定是否扩展。

三阶段验收说明 ↗知识体系提纲 ↗仓库 README ↗