常见问题

#这和 Hexo 版的 Fluid 是什么关系？

Fluid for Astro 是社区移植版本，视觉与交互尽量与 hexo-theme-fluid 保持一致，但代码完全基于 Astro 重写。

它不是 Hexo 主题的 npm 包，也不能直接在 Hexo 中使用。Hexo 版的配置项（_config.yml）被翻译成了 src/config.ts 中的 TypeScript 对象。

#如何从 Hexo 迁移？

大致步骤：

1. 把 Hexo 的 source/_posts/*.md 复制到 src/content/posts/。
2. 调整 front matter：
   • index_img → indexImg
   • banner_img → bannerImg
   • banner_img_height → bannerImgHeight
   • banner_mask_alpha → bannerMaskAlpha
   • sticky、tags、categories 保持不变
3. 把图片放到 public/img/，并把文章中的图片路径改成 /img/...。
4. 把 _config.yml 中的设置迁移到 src/config.ts。
5. 运行 npm run dev，逐页检查。

Hexo 的 tag 插件（{% note %}、{% fold %}、{% mermaid %} 等）不会自动转换。可以用 Markdown 引用、<details> 标签或 Mermaid 代码块替代。

#为什么评论没有显示？

按顺序检查：

1. postConfig.comments.enable 是否为 true。
2. postConfig.comments.type 是否与 commentsConfig 中已填写的 provider 一致。
3. 对应 provider 的必要参数是否完整，例如 Giscus 需要 repo 与 repoId。
4. 文章 front matter 中是否设置了 comments: false。

如果 provider 配置不完整，组件会安静地不渲染，以免在页面上留下空白区域。

#为什么搜索没有结果？

• 确认 searchConfig.enable 为 true。
• 确认构建后存在 dist/search.json。
• 如果 searchConfig.content 为 false，搜索只会匹配标题。
• 开发模式下首次打开搜索框需要等待索引加载完成。

#如何修改样式？

有两种方式：

方式一：修改配置。 颜色、字体、圆角、头图高度等都在 src/config.ts 中。

方式二：追加自定义 CSS。 把 CSS 文件放到 public/css/custom.css，然后在配置中引用：

export const customConfig: CustomConfig = {
	css: "/css/custom.css",
	js: "",
	head: "",
	html: "",
};

Fluid 的样式源码位于 src/styles/fluid/，使用 Stylus 编写。直接修改源码也可以，但升级主题时需要手动合并改动。

#为什么头图不显示？

• bannerImg 路径是否以 / 开头？它相对于 public/ 目录。
• 图片文件是否真的存在于 public/img/？
• bannerImgHeight 是否为 0？为 0 时头图高度为零。

#支持 MDX 吗？

当前模板只启用了 .md。如果需要 MDX，可以安装 @astrojs/mdx 并在 astro.config.mjs 中添加集成。内容集合也需要相应调整。

#可以只用其中的某些页面吗？

可以。Astro 的文件路由意味着删除 src/pages/links.astro 就会移除友链页。记得同时清理导航菜单中的对应链接。

#如何更新依赖？

npm outdated
npm update

Astro 的大版本升级可能包含破坏性变更，建议先阅读 Astro 升级指南，并在独立分支中测试。

#发现 Bug 怎么办？

请在仓库中提交 Issue，并附上：

• 复现步骤
• 浏览器与操作系统
• 相关配置片段
• 控制台报错（如果有）

如果方便，附上一张截图会更有帮助。