Hexo 文章资源与站内链接：图片、代码和永久链接的组织方法
文章一旦不再只有文字，就会遇到三个实际问题：图片放在哪里，代码怎样保持可读，文章之间怎样互相引用而不在改标题后全部失效。Hexo 给了我们多种选择，但个人博客最需要的不是“全部都用上”，而是先定一套容易维护的边界。
共享图片放在哪里
当前仓库把可复用的小图片放在 source/images，例如公安备案图标和站点公共图片。文章里可以使用站点根路径引用：
这类资源适合头像、Logo、备案图标和多个页面都可能用到的图片。它们不属于某一篇文章，文件名和路径应该尽量稳定。
文章专属的大图不建议随意塞进 source/images。这样做短期很方便，时间长了却很难判断图片属于哪篇文章，也不容易清理历史资源。对于较大的媒体或跨文章复用的资源，先确认图床地址和生命周期，再决定是否使用外部地址。
文章资源文件夹
项目的 _config.yml 打开了 post_asset_folder: true，说明可以为文章准备同名资源目录。新文章需要使用专属图片时，可以把资源放在对应的文章资源目录，并使用 Hexo 的资源标签：
{% asset_img screenshot.webp 发布页面截图 %}
这种写法让 Hexo 参与资源路径生成，文章移动或 permalink 调整时更容易保持一致。资源文件名使用英文小写和连字符，避免空格、中文编码和大小写差异带来的跨平台问题。
不是每张图都值得单独建资源目录。小而通用的图片继续放 source/images；只服务一篇文章的截图、流程图和示例图再考虑文章资源目录。先按归属划分，后面维护会轻很多。
代码块要告诉读者语言
Markdown 代码块最好写明语言。PowerShell 示例可以写成：
pwsh ./ops/check.ps1
YAML 示例可以写成：
title: 示例标题
draft: false
在 Markdown 文件中把这些行放进对应的语言代码围栏即可。语言标记可以让主题使用正确的高亮规则，也能让读者知道这段代码应该在哪个环境执行。命令示例尽量保持可复制，说明放在代码块前后，不要把大量解释混进命令本身。
代码块里的路径、环境变量和主机信息也要遵守安全边界。可以写 BLOG_HOST、BLOG_PATH 这样的变量名，不能把私钥内容、密码或临时令牌复制进文章。需要展示敏感值的位置，使用明确的占位符，并告诉读者从自己的环境读取。
用稳定路径做站内链接
当前博客的 permalink 是 year/month/day/title。文章文件名中的 slug 会进入 title 部分，因此我会给文章使用稳定的英文文件名，然后在 front matter 里写中文标题。
文章互链使用站点根路径：
[Front Matter 指南](/2026/07/31/hexo-front-matter-guide/)
这种写法不依赖当前文章所在目录，也不会因为 Markdown 文件在仓库里移动而改变。链接目标的日期和 slug 必须与实际文章一致，发布前可以从 public/ 中确认对应的 index.html 是否存在。
如果只是引用仓库说明文档，使用仓库路径更合适，例如 docs/05-构建与部署.md。docs/ 不会被 Hexo 当作文章生成到站点，所以不要把它写成一个假装存在的站内页面。
中文标题和英文 slug 的取舍
中文标题更适合读者，英文 slug 更适合长期维护。两者分工清晰：
- title 表达文章主题；
- 文件名提供稳定的 URL 片段；
- date 参与日期目录；
- 站内链接使用最终生成的路径。
如果文章已经发布，不要为了追求更短而频繁修改文件名。需要改标题时，先确认是否会影响读者理解；需要改 slug 时，先评估旧链接是否已经被外部引用。
三步排查死链
第一步，确认 Markdown 中的路径以 / 开头或使用正确的资源标签，不要依赖当前页面的相对目录猜测。
第二步，运行构建，检查 public/ 下是否生成文章页面和资源文件：
pwsh ./ops/build.ps1
第三步，在生成的 HTML 中搜索目标路径，确认链接和图片引用真的写入页面。这样能发现“Markdown 看起来没问题，但文件没有被复制到 public/”的情况。
如果是外部图片，先在浏览器中确认地址返回成功，再把它写进文章。无法确认长期可用性的地址就不要急着发布。
小结
资源组织的原则可以归纳成三句话：公共图片放公共目录，文章专属资源跟随文章，外部资源先确认再引用。代码块写明语言，站内链接使用稳定路径，构建产物负责最后验收。
如果你还在整理元数据，可以阅读Hexo Front Matter 详解；资源准备好之后，再按照构建与部署排障指南检查页面是否真的上线。