hexo博文图片及与Typora一致

这篇记录如何让 Hexo 与 Typora 插入/预览图片保持一致，并从旧的 hexo-asset-image 迁移到 hexo-image-link。目标是：Typora 本地能看，部署上线也能看，而且不用写 {% asset_img %} 这样的标签。

1. 卸载 `hexo-asset-image`

这个老插件在新版 Hexo 下容易与资源文件夹机制冲突，建议移除：

npm uninstall hexo-asset-image --save

卸载后，检查 package.json，若还有残留条目，手工删掉并执行：

npm install

2. 安装 `hexo-image-link`

用来自动把 Markdown 里的图片链接解析成正确路径：

npm install hexo-image-link --save

无需在文章里写 {% asset_img %}，保持纯 Markdown 即可。

3. 启用文章资源文件夹（配合 Typora 最稳）

编辑站点根目录的 _config.yml（不是主题配置）：

post_asset_folder: true

建议同时保持 Hexo 的默认渲染器（如 hexo-renderer-marked），避免与路径改写类插件冲突。

4. 推荐的文件与引用方式

假设你的文章是 hexo博文图片及与Typora一致.md：

source/_posts/
  hexo博文图片及与Typora一致.md
  hexo博文图片及与Typora一致/
    image-1.png
    keyboard-shortcuts-win.png
    keyboard-shortcuts-macos.png
    keyboard-shortcuts-linux.png

在 Markdown 中使用纯相对路径（Typora 与 Hexo 都能识别）：

![](./image-1.png)
![](./keyboard-shortcuts-win.png)
![](./keyboard-shortcuts-macos.png)
![](./keyboard-shortcuts-linux.png)

只要图片放在文章同名文件夹里，并用 ./文件名 这种写法，就能在 Typora 本地预览 + Hexo 生成后正常访问。

5. Typora 设置建议

偏好设置 → 图像：
- 「插入图片时复制到」：./${filename}/
- 勾选「使用相对路径」
这样粘贴图片时会自动进入文章同名文件夹，并写成 ./xxx.png。

6. 生成与验证

hexo clean && hexo g && hexo s

浏览器打开 http://localhost:4000 检查图片显示是否正常。

7. 常见问题排查

首页/归档页不显示但文章页能显示

多半是装了会改写 <img src> 的插件（懒加载、路径清洗等）。请逐个禁用后再测试。
与本方案冲突较多的老插件：hexo-asset-image（已卸）、某些 lazyload/shortcode 过滤器等。

部署后 404 / 路径错位

检查站点 _config.yml 的 url/root 与部署的路径一致：
- 用户主页：root: /
- 项目页：root: /你的仓库名/
确认图片确实位于 source/_posts/文章同名文件夹/ 内。

Typora 里路径被写成 文章名/图片.png

把链接改成 ./图片.png（相对路径）；
确保 Typora 的「路径前缀模板」留空，开启「使用相对路径」。

8. 小结

卸载 hexo-asset-image，安装 hexo-image-link。
开启 post_asset_folder: true，图片放入文章同名文件夹。
文章里用纯 Markdown 相对路径（./xxx.png）。
避免再用 {% asset_img %}，保证 Typora 与 Hexo 一致预览。

完成以上配置后，写作体验就能「所见即所得」，部署也不再踩坑。祝写博愉快～ 🎉

::contentReference[oaicite:0]{index=0}