常见问题

十个能解释「它怎么会长这样」的答案。

页面上没有语言切换

这是对的。切换按钮只在另一种语言存在同一页面时才渲染。没有译文的文章、只在 一种语言里出现的标签,都不会有按钮。

分类按名字匹配,并为意译情况留了一张小别名表(Setup ↔ 配置、Design ↔ 设计)。 需要新的对应关系就加进 src/data/taxonomy.ts。

分类卡片的图不对,或者只显示一个字

卡片封面优先取 src/data/taxonomy.ts,没有就取该分类最新文章的封面,再没有就是 首字占位。想固定下来就写进映射:

ts
export const categoryMeta = {
  技术: { cover: '/img/tech.jpg' },
};

标题变成「你好 — inspos — inspos」

Base.astro 会自动在传入的 title 后面拼站点名。只传短标题(你好),不要再带 — inspos。

构建失败,但 npm run dev 正常

npm run build 会先跑 astro check,开发服务器不会。最常见的是隐式 any:

plaintext
error ts(7006): Parameter 'x' implicitly has an 'any' type.

补上类型((x: string) => …)再构建。想去掉这道闸就直接 npx astro build,代价是类型错误进生产。

新写的文档页没出现在侧栏

文档按目录分组:getting-started/、configuration/、content/、reference/。 放进别的目录,页面能构建出来但没有入口——侧栏只认 src/lib/docs.ts 里列出的章节。 把文件挪进已有章节,或在那里新增一个章节。

搜索不到刚发的文章

搜索索引由 Pagefind 在构建时生成(scripts/build.mjs)。重新 npm run build; npm run dev 不写索引。

图片 404

正文图片必须放 public/,且从站点根引用:/img/hello.jpg,不能写 ../assets/hello.jpg。 构建会原样拷贝 public/。

zh-Hant 页面里还是简体

zh-Hant 复用 posts-zh/ 的文章,只转换界面文案,不转换你的正文。正文还是简体, 说明那段字写在内容里——直接写成繁体,或在 src/lib/trad.ts 里补词条。

草稿本地能看,线上没有

设计如此。draft: true 的文章在开发模式可见、不进构建产物。发布前改成 draft: false, 并确认 date 不是未来日期。

到底改 site.config.yaml 还是 src/?

读者能看到的文字、链接、配色、功能开关 → site.config.yaml。 改主题本身(布局、组件、样式)才动 src/。凡是已经配置化的属性,改 src/ 等于下次主题更新会被覆盖。

还是不明白

对 dist/ 跑一次 npm run seo:它会报缺失的 meta、重复标题、不对等的 hreflang、 过薄的页面——「奇怪」通常就出在这几项上。