常见问题

add 返回 401

服务器要求令牌认证。交互终端会提示输入；非交互脚本用 --token 传入。令牌输错过期后删除凭据缓存中对应条目即可重新输入，缓存位置见站内搜索 ?config.yaml。

add 返回 409「站点名已存在」

同名站点已注册。更新内容的正确姿势是先 del 后 add，见站内搜索 ?更新站点。

add 返回 422「git 克隆失败」

服务器无法克隆该仓库：检查仓库地址拼写、服务器到仓库的网络可达性，以及地址是否确实指向 git 仓库。

preview 端口被占用

EADDRINUSE 时换端口：docdoc preview ./my-docs --port 3100。

用域名访问返回 404

域名路由优先于路径前缀：域名必须已通过 add --domain 注册到某站点，并已解析到本机。未绑定时用 http://服务器:端口/<站点名>/ 访问。

git 源预览为什么不自动重建

文件监听只对本地源生效；git 源是一次性快照，修改仓库后重新执行 preview。

证书迟迟不签发

按序核对：域名解析到本机、HTTPS 监听端口与 80 公网可达且未被占用、tls.enabled 为 true、配置已重载；自定义了 tls.httpPort 时确认外部 80 已映射到该端口。联调阶段把 directoryUrl 切到 staging 地址排除 Let's Encrypt 速率限制。

页面标题不对

页面标题取每个文件的第一个一级标题（# 标题）；文件缺少一级标题时按文件名兜底。