常见问题

开发环境

Node.js 版本不兼容

确保使用 Node.js >= 18。推荐使用 nvm 管理多版本：

nvm install 22nvm use 22node -v

npm install 失败

# 清除缓存重试npm cache clean --forcerm -rf node_modules package-lock.jsonnpm install

启动 dev server 报错

常见原因：

• 端口被占用：Astro 开发服务器默认使用 4321 端口
• 依赖版本不匹配：删除 node_modules 后重新 npm install

内容编写

文章不显示在页面上

确认步骤：

1. 文件位于 src/content/ 对应的集合目录下
2. sections.json 中配置了对应的 articleConfig
3. content.config.ts 中注册了集合
4. Front Matter 格式正确且 title 字段存在

CodeBlock 组件报 “Expected component to be defined”

MDX 文件中使用 CodeBlock 等 Astro 组件前，必须在 Front Matter 之后先 import：

---title: 示例---import CodeBlock from '@/components/CodeBlock.astro';<CodeBlock type="terminal" code="npm run build" />

构建部署

构建输出警告 “Shiki instances”

这是 Shiki 语法高亮器在 SSG 构建时的正常行为，已在构建脚本中过滤，不影响功能和性能。

搜索索引中部分 URL 404

搜索索引 URL 由 scripts/generate-search-index.js 生成，如果新增了特殊路由的手册（如 manuals/ 下新增子目录），需要在该脚本中添加对应的 URL 映射规则。