fox小栖共创博客

本地正常、GitHub 线上图片/音乐失效终极解决实录

 
  • wuli
  • Mar 04, 2026
  • 0 views

Jekyll TeXt 主题博客：网页音乐&图片路径避坑完整解决方案

一、前言

在使用 Jekyll + TeXt 主题 搭建 GitHub Pages 博客时，经常遇到一个经典问题：

本地预览图片、音乐都能正常加载播放，一旦上传到 GitHub Pages 线上，图片无法渲染、MP3 音频无法播放。

先后尝试了网易云内嵌播放器、iframe 外链播放器、Markdown 同级相对路径、_assets 资源目录等多种方式，踩遍所有坑，本文完整记录全过程、失败原因、最终规范配置，同时总结通用路径规范，后续写博客直接套用即可。

二、前期尝试：第三方音乐嵌入方案（全部失败）

1. TeXt 主题自带网易云音乐播放器

TeXt 主题内置了网易云音乐扩展标签，直接引入歌单 ID 即可嵌入：

- 恋人
<div><iframe class="extensions extensions--audio" width="330" height="86"
  src="//music.163.com/outchain/player?type=2&id=2600493765&auto=1&height=66"
  frameborder="no" border="0" marginwidth="0" marginheight="0">
</iframe>
</div>

- 你的酒馆对我打了烊
<div><iframe class="extensions extensions--audio" width="330" height="86"
  src="//music.163.com/outchain/player?type=2&id=1341964346&auto=1&height=66"
  frameborder="no" border="0" marginwidth="0" marginheight="0">
</iframe>
</div>

2. 网易云官方 Outchain iframe 外链播放器

使用网易云公开外链播放器嵌入网页：

- 恋人
<iframe frameborder="no" border="0" marginwidth="0" marginheight="0" width="330" height="86" 
src="https://music.163.com/outchain/player?type=2&id=2600493765&auto=0&height=66">
</iframe>

- 你的酒馆对我打了烊
<iframe frameborder="no" border="0" marginwidth="0" marginheight="0" width="330" height="86" 
src="https://music.163.com/outchain/player?type=2&id=1341964346&auto=0&height=66">
</iframe>

3. 失败核心原因

  1. 网易云、QQ 音乐等平台严格防盗链 + 版权限制；
  2. VIP 歌曲、版权受限歌曲，外链/iframe 一律无法跨域播放；
  3. 平台对外链播放器做 Referer、IP 校验，GitHub Pages 域名直接被拦截；
  4. 依赖第三方平台外链，完全不受自己控制，随时失效。

结论：想在博客稳定无限制播放音乐，放弃第三方平台外链，改用本地 MP3 自主托管是唯一可行方案。

三、尝试一：MP3 与 Markdown 文章同级存放

目录结构

把音频和文章都放在 _posts 目录下：

_posts/
├─ test音乐播放器.md
└─ 恋人.mp3

嵌入播放代码

<audio controls preload="none" style="width:100%;">
<source src="恋人.mp3" type="audio/mpeg">
你的浏览器不支持音频播放，请更换浏览器尝试。

现象与原因

  • ✅ 本地 Jekyll 预览：可以正常播放
  • ❌ 上传 GitHub Pages：完全无法加载

根本原因：

  1. _posts 是 Jekyll 特殊目录，仅负责渲染文章，不适合存放静态资源；
  2. 使用相对路径 恋人.mp3，本地路由适配，GitHub Pages 根路由解析错乱；
  3. TeXt 主题路由规则下，_posts 内静态资源线上不会被正常分发。

同时过往图片也出现同款问题：图片放 _posts 本地能看，线上直接丢失，属于同一路径规则问题。

四、尝试二：自建资源目录 assets 规范托管

1. 标准目录结构（最终可用版）

关键：文件夹不能带下划线，必须是纯 assets

myblog/
├─ _posts/                # 所有博客文章存放处
│  └─ test音乐播放器.md
└─ assets/                # 静态资源根目录（无下划线）
   ├─ images/             # 图片总目录
   │  └─ src-img/         # 分组图片文件夹
   │     ├─ image-1.png
   │     └─ image-2.png
   └─ music/              # 音乐MP3目录
      └─ lover.mp3        # 建议改用英文文件名

2. 图片标准引入写法（本地 + 线上通用）

采用网站根目录绝对路径，以 / 开头：

![00桌宠](/assets/images/src-img/image-1.png)
  • ✅ 适配 TeXt 主题、本地预览、GitHub Pages
  • ✅ 永久稳定，后续所有图片统一放 assets/images 即可

3. MP3 音频标准嵌入写法

<audio controls preload="none" style="width:100%;">
    <source src="/assets/music/lover.mp3" type="audio/mpeg">
  你的浏览器不支持音频播放，请更换浏览器尝试。

关键避坑点

  1. ❌ 禁止使用 _assets 带下划线目录：Jekyll 会直接忽略下划线开头文件夹，线上不发布；
  2. ❌ 禁止中文文件名音频：GitHub Pages 对中文 MP3 兼容性极差，图片可兼容、音频极易加载失败，建议统一改成英文命名；
  3. ❌ 禁止使用 ./ ../ 相对路径，统一用 /assets/分类/文件名 绝对根路径；
  4. 静态资源全部统一放进 assets，不要散落在 _posts 或其他自定义目录。

五、Jekyll + TeXt 静态资源路径通用规范（总结）

1. 固定目录约定

  • 文章：统一放在 _posts
  • 图片：统一放在 assets/images/ 下级可建子文件夹
  • 音频/视频：统一放在 assets/music/
  • 其他文件：assets/files/

2. 通用引入格式

  • 图片：![描述](/assets/images/子目录/图片名.png)
  • 音频：<audio src="/assets/music/英文文件名.mp3" controls style="width:100%;">

3. 永久避坑口诀

  1. 静态资源绝不放 _posts；
  2. 资源目录不用下划线，只用 assets；
  3. 全部用以 / 开头的根绝对路径，不用相对路径；
  4. 音频、视频文件名只用英文/数字，不用中文和空格；
  5. 放弃网易云/QQ 音乐外链，自主托管 MP3 永久无版权限制、无播放限制。

六、最终效果

按照上述规范配置后：

  • 本地 Jekyll 预览：图片正常渲染、音乐正常播放；
  • 上传 GitHub Pages 线上：图片、音频全部稳定加载，无任何失效问题；
  • 后续所有博客文章，直接套用这套目录和路径写法，再也不会出现本地正常线上失效的问题。

00桌宠