WordPress自定义图片/HTML插入及主题媒体文件夹404问题排查

1. 如何在WordPress中插入自定义图片和HTML代码？ #

插入自定义图片 #

• 编辑器可视化操作：
  • 古腾堡编辑器：点击右上角的+按钮，搜索「图片」块，选择「上传」本地图片或者从「媒体库」挑选已上传的图片，还能在块设置里调整尺寸、对齐方式等属性。
  • 经典编辑器：点击工具栏的「添加媒体」按钮，完成图片上传/选择后，直接插入到内容区域即可。
• 主题/插件代码中插入：
  要是需要在模板文件（比如index.php、single.php）里硬编码图片，一定要用WordPress内置函数获取正确路径，避免404错误：

  <!-- 示例：图片放在主题目录的images文件夹下 -->
  <img src="<?php echo get_template_directory_uri(); ?>/images/your-custom-img.jpg" alt="图片描述文本">
  

  如果用的是子主题，记得换成get_stylesheet_directory_uri()，它会优先指向子主题目录。

插入自定义HTML代码 #

• 编辑器中插入：
  • 古腾堡编辑器：添加「自定义HTML」块，直接在块内编写或粘贴HTML代码，切换到预览模式就能看到效果。
  • 经典编辑器：切换到「文本」标签页，直接输入HTML代码；可视化模式下可能会过滤部分代码，所以优先用文本模式。
• 模板文件中插入：
  直接在主题模板（比如header.php、footer.php）里写HTML代码就行，比如添加一个自定义宣传横幅：

  <div class="custom-banner">
    <h3>欢迎来到我的个人博客</h3>
    <p>这里有你感兴趣的技术内容</p>
  </div>
  

• 短代码复用HTML（适合重复使用的场景）：
  在主题的functions.php里注册一个短代码，方便后续随时调用：

  function custom_card_shortcode() {
    return '<div class="info-card"><p>这是可重复使用的自定义卡片</p></div>';
  }
  add_shortcode('info_card', 'custom_card_shortcode');
  

  之后在编辑器里输入[info_card]，就能快速插入这段HTML内容。

2. 主题目录下媒体文件夹图片404错误的解决办法 #

你踩的坑是路径引用逻辑错误——直接用相对路径的话，浏览器会从网站根目录（也就是你看到的/html/）去查找图片，而不是从你的主题目录里找。

正确的解决方式：用WordPress内置函数获取主题URL #

WordPress提供了get_template_directory_uri()函数，它会返回当前主题目录的完整绝对URL（比如http://你的域名/wp-content/themes/theme-name/），用它来拼接图片路径就不会错了。

把index.php里的图片引用改成这样：

<img src="<?php echo get_template_directory_uri(); ?>/media/sampleIMG.jpg" alt="示例图片">

为什么之前的路径会失效？ #

举个例子：你的index.php在/wp-content/themes/theme-name/目录下，你直接写media/sampleIMG.jpg时，浏览器会把它解析为相对于当前页面的路径——如果你的首页URL是http://你的域名/，浏览器就会请求http://你的域名/media/sampleIMG.jpg（对应服务器路径/html/media/sampleIMG.jpg），但你的图片实际在/wp-content/themes/theme-name/media/里，自然会返回404。

如果是子主题开发，记得换成get_stylesheet_directory_uri()，它会优先指向子主题目录，更符合子主题的使用规范。

内容的提问来源于stack exchange，提问作者Fatih Tunç