常见问题

预览打不开或 404

确认工作区路径。serve 的 --work-dir 应指向包含 __everkm/ 与 Markdown 内容的站点根目录：

cd my-site          # 站点根
everkm-publish serve

若在子目录（如 theme-youlog 的 __everkm/) 开发主题，需显式指定：

everkm-publish serve --work-dir ../ --theme youlog --theme-dev

默认监听 http://localhost:9081。健康检查：GET /__everkm/state/ping 应返回 PONG。

首页空白或样式错乱

1. 确认已安装主题：__everkm/theme/youlog/ 存在，或执行 everkm-publish theme install everkm/youlog
2. 根目录需有首页内容：如 HOME.md 且 Front Matter 含 slug: index（见 文章元数据）
3. 修改主题源码后，开发模式加 --theme-dev 并重启或等待重载

找不到主题 / theme not found

everkm-publish theme install everkm/youlog@<版本>
everkm-publish serve --theme youlog

--theme 名称对应 __everkm/theme/<name>/ 目录名，不是 everkm/youlog 中的作者前缀。远程安装写法见 快速开始。

本地开发时可指定主题目录，跳过已安装包：

everkm-publish serve --theme-dir ./path/to/theme/youlog

lint 报内链歧义

正文 [[...]] 匹配到多个页面时会按行号报错。处理方式：

• 改用更具体的路径，如 [[docs/guide/quick-start]] 而非 [[quick-start]]
• 检查是否有重复 slug 或同名文件
• 运行 everkm-publish lint ./my-site --auto-fix 修复可自动处理项

内链规则见 链接与内链。

lint 报 Front Matter 问题

常见项：

报错	处理
缺少 created_at	补 RFC3339 时间，或 --auto-fix
date 已废弃	改为 created_at
slug 冲突	修改重复 slug 或让 lint 删行（auto-fix）
缺少 id	--auto-fix 可自动补全

详见 文章元数据。

导出后缺少图片或附件

导出只包含正文被引用的资源。未在 Markdown 中引用的文件不会进入 dist/。

需要额外发布时：

• 放入 __everkm/extend/assets/，导出时复制到站点 assets/
• 或在正文中用标准链接 / media() / dCard 引用，使其进入抓取图

见 导出与发布。

多语言内容不显示

多语言站需在语言子目录下放置对应 Markdown：

my-site/zh_CN/blog/hello.md
my-site/en_US/blog/hello.md

预览时指定语言：

everkm-publish serve --lang zh_CN

或在浏览器用 ?_lang=zh_CN。未指定 --lang 时内容根为工作区根目录（单语言模式）。见 多语言。

配置改了但页面没变

修改内容	是否需要重启
Markdown 正文	否，刷新即可
__everkm/i18n/ 语言包	否
extend/ 模板或资源	否（触发重载）
everkm.yaml 部分项	视项而定；folders 变更通常需重启 serve
主题包（非 --theme-dev）	需重启

主题开发请加 --theme-dev 监听主题目录变更。

旧目录迁移（v0.17.2）

以下路径已废弃，请迁至 __everkm/extend/：

旧路径	新路径
__public	extend/pages
__assets	extend/assets
__dcard	extend/dcard
__everkm/__theme	__everkm/theme

详见 快速开始 与 更新日志。

导出后如何部署

导出目录即为静态站根目录，上传到 Nginx、对象存储、Vercel 等即可。推荐流程：lint → serve --export → web ./dist 本地验 → 上传。见 导出与发布。

搜索框不出现

1. 主题需支持搜索（如 youlog + plugin-in-search 构建产物）
2. everkm.yaml 中配置 config.algolia_search（不是 embed_search）
3. 需先按 嵌入式搜索 推送索引

见 嵌入式搜索。

主题开发与站点使用混淆

角色	关注点
站点运营者	my-site/ 写内容、everkm.yaml、快速开始
主题开发者	主题源码、everkm-render.js、打包 zip，见 主题开发

主题（Theme） 是完整外观包；页面模板（Template） 是主题内某一类页面的渲染方式（如 book、list）。见 概念与架构。