图片显示问题解决方案

问题现象 ¶

在本地 Markdown 文件中，语雀 CDN 的图片链接（如 https://cdn.nlark.com/yuque/...）可以正常显示，但上传到 GitHub Pages 后图片无法显示。

问题原因 ¶

语雀 CDN ( cdn.nlark.com ) 的图片在 GitHub Pages 上无法显示的主要原因：

1. 防盗链保护：语雀 CDN 会检查 HTTP Referer 头，GitHub Pages 的域名不在允许的白名单中
2. 访问权限：语雀的图片可能需要登录权限才能访问
3. 跨域限制：某些 CDN 服务不允许从其他域名引用资源

解决方案 ¶

方案一：下载图片到本地（已实施）¶

已完成的操作： - 创建了自动下载脚本 download_yuque_images.py - 批量下载了 109 张语雀图片到 F:\Notebook\mkdocs-site\docs\Courses\Images\ 目录 - 自动替换了 6 个 Markdown 文件中的图片链接 - 将外部链接改为相对路径链接

处理结果： - 原链接：![](https://cdn.nlark.com/yuque/0/2025/png/38851158/1764031132724-f12b7bd1-4b8a-4095-aa2e-a4b68a920d5e.png) - 新链接：![](../Images/1764031132724-f12b7bd1-4b8a-4095-aa2e-a4b68a920d5e.png)

优点： - 完全可控，不依赖外部服务 - GitHub Pages 可以正常显示 - 加载速度快 - 可以对图片进行优化和版本控制

注意事项： - 需要将 Images 目录也上传到 GitHub - 图片会占用仓库空间 - 如果有新的语雀图片，需要重新运行脚本

方案二：使用图床服务（备选）¶

如果你不想把图片存放在 GitHub 仓库中，可以考虑使用支持公共访问的图床：

推荐图床服务： 1. GitHub 自身：将图片放在独立仓库中，使用 GitHub Pages 或 raw.githubusercontent.com 访问 2. 图床服务：imgbb、Cloudinary、jsDelivr 等 3. 对象存储：阿里云 OSS、腾讯云 COS、七牛云等

示例链接格式：

# GitHub raw 链接
<div markdown="1" style="margin-top: -30px; font-size: 0.75em; opacity: 0.7;">
:material-circle-edit-outline: 约 1067 个字 :fontawesome-solid-code: 29 行代码 :material-clock-time-two-outline: 预计阅读时间 5 分钟
</div>
![](https://raw.githubusercontent.com/yourusername/your-repo/main/path/to/image.png)

# jsDelivr CDN 加速
![](https://cdn.jsdelivr.net/gh/yourusername/your-repo@main/path/to/image.png)

方案三：使用反代服务（不推荐）¶

使用反向代理服务来绕过防盗链，但这种方式不稳定且可能违反服务条款。

后续建议 ¶

1. 提交更改到 Git ¶

将处理后的文件提交到 GitHub：

cd F:\Notebook\mkdocs-site
git add docs/Courses/
git commit -m "将语雀图片下载到本地并更新链接"
git push

2. 更新 MkDocs 配置（如果使用）¶

如果你使用 MkDocs 构建网站，确保配置正确：

# mkdocs.yml
site_name: 你的网站名称
docs_dir: docs

# 如果图片在 docs 目录下，默认就可以访问
# 如果在网站根目录的 Images 目录，可能需要添加
extra:
  image_path: ../Images

3. 处理新图片 ¶

如果你从语雀导出了新的笔记，包含新的图片：

# 运行下载脚本
python c:\Users\90645\WorkBuddy\Claw\download_yuque_images.py

4. 可选：优化图片 ¶

可以进一步优化图片以减小文件大小：

# 使用 Pillow 库压缩图片
from PIL import Image

def optimize_image(input_path, output_path, quality=85):
    img = Image.open(input_path)
    img.save(output_path, optimize=True, quality=quality)

验证步骤 ¶

1. 本地预览：使用 MkDocs 本地服务器预览，确认图片显示正常

   cd F:\Notebook\mkdocs-site
   mkdocs serve
   

2. 提交到 GitHub：推送更改到远程仓库

3. 检查 GitHub Pages：访问你的 GitHub Pages 网站，确认图片正常显示

技术细节 ¶

下载脚本说明 ¶

download_yuque_images.py 脚本功能：

1. 遍历所有 Markdown 文件：在 F:\Notebook\mkdocs-site\docs\Courses\ 目录下递归搜索 .md 文件
2. 识别语雀图片链接：使用正则表达式匹配 https://cdn.nlark.com/yuque/ 开头的链接
3. 下载图片：将图片下载到 Images 目录
4. 自动重命名：如果文件名冲突，自动添加序号
5. 替换链接：将外部链接替换为相对路径 ../Images/filename.png
6. 统计信息：显示处理进度和结果统计

正则表达式 ¶

# 匹配语雀图片链接
pattern = r'!\[\]\((https://cdn\.nlark\.com/yuque/[^\)]+)\)'

这个正则表达式匹配标准的 Markdown 图片链接，其中 URL 以 cdn.nlark.com/yuque/ 开头。

常见问题 ¶

Q: 为什么本地能显示，GitHub Pages 不能？¶

A: 本地浏览器没有防盗链限制，且你可能已经登录过语雀。GitHub Pages 是公共服务，有跨域和防盗链限制。

Q: 图片下载失败怎么办？¶

A: 检查网络连接，确认图片链接是否仍然有效。某些语雀图片可能已被删除或设置了访问权限。

Q: 会占用大量仓库空间吗？¶

A: 109 张 PNG 图片大约几十 MB。如果图片很多，建议使用图床服务。

Q: 如何处理 SVG 图片？¶

A: 当前脚本主要处理 PNG/JPG/GIF 格式。如果有 SVG 图片，可以手动下载或修改脚本。

总结 ¶

推荐使用方案一（本地存储），因为： - 完全可控，不依赖第三方服务 - 稳定可靠，不会因为外部服务变更而失效 - 适合个人博客、技术文档等场景 - 便于版本管理和协作

如果图片数量很大（数百张以上）或文件很大（每张超过几 MB），可以考虑使用图床服务。

创建时间: 2026-03-12 处理文件数: 6 个 Markdown 文件 下载图片数: 109 张 图片目录: F:\Notebook\mkdocs-site\docs\Courses\Images\