博客发布踩坑经验

标签

blog

vitepress

nolebase

经验

字数

458 字

阅读时间

2 分钟

时间

2026-05-16

背景

通过 AI Agent 操控飞牛 NAS 的经验整理成文章，发布到 VitePress 博客。

踩坑记录

坑1: 侧边栏不显示文章

现象：文章直接访问能打开，但左侧侧边栏选单里找不到

原因：update.ts 脚本只处理子文件夹里的文章，放在 笔记/ 根目录的单个 md 文件不会进入侧边栏

解决方案：把文章放到子文件夹，如 笔记/AI_Agent折腾/文章名.md

坑2: Vercel 构建后侧边栏空白

现象：本地开发正常，Vercel 部署后侧边栏没有新文章

原因：docsMetadata.json 被 .gitignore 忽略，是构建时动态生成的。但 Vercel 构建命令没有运行 pnpm update

解决方案：Vercel 构建命令改为 pnpm update && pnpm docs:build

坑3: pnpm approve-builds

现象：新 clone 项目后 pnpm install 失败

原因：esbuild、sharp、vue-demi 需要编译，被 pnpm 跳过

解决方案：创建 pnpm-workspace.yaml：

allowBuilds:
  esbuild: true
  sharp: true
  vue-demi: true

正确的博客发布流程

1. git clone 仓库
2. 创建 pnpm-workspace.yaml（如果是新环境）
3. pnpm install
4. pnpm run update（生成 docsMetadata.json）
5. pnpm run docs:dev（本地预览）
6. 在 笔记/子目录/ 下创建文章
7. 再次 pnpm run update（更新侧边栏）
8. 推送 GitHub → Vercel 自动部署
9. 或本地 pnpm run docs:build 后部署

关键文件位置

• 构建配置：package.json scripts
• 动态元数据：.vitepress/docsMetadata.json（由 scripts/update.ts 生成）
• VitePress 配置：.vitepress/config.ts
• 忽略文件：.gitignore（docsMetadata.json 被忽略）

相关项目

• AI_Agent折腾本地化

贡献者

yancy

文件历史

最后编辑于 大约 2 小时前查看完整历史

f5b22-docs: 添加博客发布踩坑经验文章