常见问题
Q: 必须使用 Bun 吗？可以用 Node.js 吗？
Section titled “Q: 必须使用 Bun 吗？可以用 Node.js 吗？”推荐使用 Bun。ShokaX 针对 Bun 运行时优化，Node.js 兼容性不保证。部分功能（如 vite-plugin-font 字体子集化）依赖 Bun 特性。
Q: 如何切换网站语言？
Section titled “Q: 如何切换网站语言？”在 src/theme.config.ts 中设置 locale 字段：
export default defineConfig({ siteName: "My Blog", locale: "en", // zh-CN | zh-TW | ja | en});详见 国际化文档。
Q: 如何更换头像？
Section titled “Q: 如何更换头像？”替换 src/assets/avatar.avif 文件（保持文件名不变），或通过 HyC 控制台上传。
Q: 为什么首页不显示分类卡片？
Section titled “Q: 为什么首页不显示分类卡片？”home.selectedCategories中的分类名必须与文章中的完全一致- 该分类下必须有已发布的文章
Q: 构建失败，提示内存不足？
Section titled “Q: 构建失败，提示内存不足？”尝试增加 Node.js 内存限制，或在 CI 中使用更大内存的机器。字体子集化处理大字符集时可能消耗较多内存。
Q: 部署后样式丢失？
Section titled “Q: 部署后样式丢失？”- 确认
astro.config.mjs中的site字段填写了正确的域名 - 检查
base路径配置（如果部署在子目录） - 清除浏览器缓存
Q: 开发模式下搜索不可用？
Section titled “Q: 开发模式下搜索不可用？”bun run dev 不会生成 Pagefind 索引。使用 bun run build && bun run preview 测试搜索功能。
Q: 如何创建加密文章？
Section titled “Q: 如何创建加密文章？”在 frontmatter 中设置：
---encrypted: truepassword: "my-password"---详见 加密文章文档。
Q: 草稿文章如何隐藏？
Section titled “Q: 草稿文章如何隐藏？”在 frontmatter 中设置 draft: true，或使用 hyc unpublish <搜索> 命令。
Q: 文章字数统计不准确？
Section titled “Q: 文章字数统计不准确？”统计包含所有已发布文章的正文内容。如果感觉不准，检查是否有未标记的草稿文章被计入。
Q: 如何让文章置顶？
Section titled “Q: 如何让文章置顶？”在 frontmatter 中设置 sticky: true。置顶文章始终显示在首页顶部，不占用分页配额。
Q: 如何添加评论功能？
Section titled “Q: 如何添加评论功能？”- 部署 Waline 服务端（参考 Waline 文档）
- 在
theme.config.ts中配置：
comments: { enable: true, waline: { serverURL: "https://your-waline.vercel.app" },}详见 评论系统文档。
Q: 可以使用其他评论系统吗？
Section titled “Q: 可以使用其他评论系统吗？”ShokaX 目前仅内置 Waline 支持。如需其他评论系统，需自行修改 WalineComments.svelte。
Q: AI 摘要不显示？
Section titled “Q: AI 摘要不显示？”- 确认已运行
hyc sync并看到摘要生成成功 - 检查
hyacine.yml中summary.enabled和 API 配置 - 检查
theme.config.ts中hyc.enable和hyc.aiSummary.enable
Q: AI 推荐文章不准确？
Section titled “Q: AI 推荐文章不准确？”- 尝试更换嵌入模型（更高维度）
- 降低
minSimilarity阈值 - 确保文章内容足够丰富
详见 AI 功能文档。
Q: 如何修改主题色？
Section titled “Q: 如何修改主题色？”编辑 src/styles/palette.css 中的 CSS 变量：
:root { --primary-color: #4a90d9; --text-color: #333;}Q: 如何添加自定义 CSS？
Section titled “Q: 如何添加自定义 CSS？”在 src/styles/ 目录下创建新的 CSS 文件，并在 Layout.astro 中引入。
Q: 如何修改页面布局？
Section titled “Q: 如何修改页面布局？”在 theme.config.ts 中切换双栏/三栏布局：
layout: { mode: "two-column", // 或 "three-column"}详见 布局配置文档。
Q: 如何更新 ShokaX？
Section titled “Q: 如何更新 ShokaX？”git pullbun install如果修改过源代码，建议先 git stash 暂存修改，更新后再 git stash pop。
Q: 数据库文件需要备份吗？
Section titled “Q: 数据库文件需要备份吗？”.hyacine 目录中的数据库文件可以通过 hyc sync 重新生成。建议加入 .gitignore。
Q: 如何备份整个项目？
Section titled “Q: 如何备份整个项目？”hyc backup # 备份文章和资产到 tar.gzgit push # 提交代码到远程仓库津公网安备 12011402001353 号