如何向WordPress古腾堡编辑的Astra主题页面添加自定义JS、CSS与HTML元素

你此前操作失效的核心原因通常是静态资源路径错误、jQuery依赖未提前加载、脚本加载优先级异常，或是WordPress伪静态规则拦截了根目录静态资源请求，按下面的方案操作即可正常生效：

方案1：古腾堡直接插入（仅单页面使用时首选，无需修改主题文件） #

• 先将自定义元素对应的CSS代码全部复制，进入 WordPress 后台 → 外观 → 自定义 → 额外CSS，粘贴后保存即可全局生效，无需单独上传CSS文件。
• 打开首页的古腾堡编辑页面，添加一个「自定义HTML」区块，将你写好的自定义元素HTML代码完整粘贴到区块内。
• 对原有JS代码做兼容处理：由于WordPress内置的jQuery默认不暴露$别名，你需要将所有JS逻辑用以下代码包裹，避免$未定义报错：

jQuery(document).ready(function($) {
  // 此处粘贴你原有所有JS、jQuery逻辑代码
});

• 回到古腾堡编辑页，在刚才的HTML区块后新增一个「自定义HTML」区块，将处理好的JS代码用<script>标签包裹后粘贴进去，更新页面即可生效。

方案2：子主题挂载资源（多页面复用场景首选，符合WordPress开发规范） #

注意不要直接修改Astra主主题的文件，避免主题更新后自定义代码被覆盖，先安装并激活Astra官方子主题后再操作：

• 将你的CSS、JS文件分别命名为custom-element.css、custom-element.js，上传到Astra子主题的根目录下。
• 打开子主题的functions.php文件，添加如下挂载代码：

function enqueue_custom_element_assets() {
  // 仅在首页加载资源的判断逻辑，不需要限制页面可删除该行及对应的闭合大括号
  if (is_front_page()) {
    // 挂载自定义CSS
    wp_enqueue_style( 'custom-element-css', get_stylesheet_directory_uri() . '/custom-element.css', array(), '1.0.0', 'all' );
    // 挂载自定义JS，指定依赖为jquery，确保jQuery优先加载，最后一个参数设置为true代表将脚本放在页脚加载
    wp_enqueue_script( 'custom-element-js', get_stylesheet_directory_uri() . '/custom-element.js', array('jquery'), '1.0.0', true );
  }
}
add_action( 'wp_enqueue_scripts', 'enqueue_custom_element_assets' );

• 打开首页古腾堡编辑页，添加「自定义HTML」区块粘贴自定义元素的HTML代码，更新页面即可。

• 按F12打开浏览器控制台查看报错：如果提示$ is not defined就是JS代码没有加上述jQuery兼容包裹；如果提示静态资源404就是文件路径填写错误，用get_stylesheet_directory_uri获取子主题路径可避免路径错误问题。
• 不要直接将静态资源放在站点根目录引入，WordPress的伪静态规则大概率会拦截此类请求，也不利于后续站点迁移。
• 检查古腾堡自定义HTML区块内的代码是否被自动转义，若存在转义字符可切换到编辑器的代码编辑模式下粘贴代码。

内容的提问来源于stack exchange，提问作者amir