03 从零跑起来:目录、依赖与命令
结论
只想看博客,不需要启动 backend/,也不需要数据库。进入 frontend/,执行三条命令就能在 http://localhost:3000 看到首页、笔记目录和详情页:
cd frontend
npm install
npm run content:validate
npm run dev
AI 助手是后来的可选链路,涉及 Python、Postgres 和模型配置;它不属于这个系列的运行前提,入口见本系列的 09 下一步。
问题与设计
仓库根只放共享内容和工程配置,frontend/ 与 backend/ 是两个独立项目:
edwardwang-blog/
content/ 博客和 AI 共用的唯一写作源
frontend/ Nuxt 4 + npm
backend/ FastAPI + uv,博客不依赖(仅私有仓库)
infra/ 本地 Postgres、部署配置
docs/ 设计、写作、运行文档
其中 frontend/ 加上内容管线已经作为开源仓库 nuxt-blog-demo 发布,可以直接克隆运行:
git clone https://github.com/edwardwang0302/nuxt-blog-demo.git
cd nuxt-blog-demo/frontend
npm install
npm run dev
开源仓库里不含 backend/,也不含 AI 助手的聊天前端;它自带一套演示内容,和本站正在写的真实内容不是同一份。本系列讲的是博客部分,读代码时对照开源仓库即可。
这样安排的结果是:
- 前端不复制
content/,直接读仓库根目录; - 后端入库也读同一份内容,不维护第二套 Markdown;
- Node 和 Python 的依赖各自隔离,不会混在一个
node_modules或虚拟环境里。
前端命令统一在 frontend/ 下执行。npm install 除了安装依赖,还会通过 postinstall 生成 Nuxt 类型,并通过 prepare 安装仓库根的 Git hooks。第一次安装后,提交信息会走 commitlint,暂存文件会走 lint-staged。
关键代码
1. 安装与校验
cd frontend
npm install
npm run content:validate
校验通过时会打印内容总数和草稿数,例如:
内容校验通过:50 篇内容,其中 32 篇草稿。
数字会随着文章增删变化,重点不是记住数字,而是命令退出码为 0。校验失败时会一次性列出文件和字段,先修内容,不要绕过。
2. 启动开发服务器
npm run dev
默认地址是 http://localhost:3000。建议先检查四条路径:
/:首页和最新笔记;/notes:目录、系列入口和标签筛选;/notes/<slug>:任意一篇已发布文章的详情;/api/notes:页面实际使用的 JSON 数据。
/api/notes 可以先用 curl 看一眼:
curl -s http://localhost:3000/api/notes | head -c 400
如果页面空白但接口有数据,问题在页面或样式;如果接口也报错,先回到内容校验。
3. 构建一次生产产物
npm run build
npm run preview
npm run build 会先执行 prebuild,也就是 scripts/validate-content.mjs;内容不合法时构建直接失败。构建成功后产物在 frontend/.output/,npm run preview 只用于本地检查生产构建,不代表生产环境配置。
4. 改代码前的质量检查
npm run lint
npm run lint:styles
npm run typecheck
npm run test
这四条分别覆盖 ESLint、Stylelint、Vue/TypeScript 类型和 Vitest 单元测试。它们比端到端测试快,适合在本地先跑;CI 还会再加 Playwright 和 axe。
验证
第一次上手,按这个顺序验收:
npm run content:validate通过;npm run dev后首页、目录、详情都能打开;- 新增一篇
draft: true的笔记,刷新/notes,确认它没有出现; - 删掉这篇测试笔记,再跑一次校验;
npm run build成功,说明内容校验和生产构建都能走通。
常见问题:
| 现象 | 优先检查 |
|---|---|
node 或 npm 找不到 |
是否安装 Node 24,终端 PATH 是否包含 Node |
| 内容校验失败 | frontmatter 必填字段、日期是否真实存在、slug 是否重复 |
| 页面 404 | 文章是否 draft: true,链接里的 slug 是否与文件名/字段一致 |
| 端口 3000 被占用 | 关闭旧进程,或使用 Nuxt 提示的其他端口 |
| 图片 404 | 图片是否放在笔记目录里,正文是否使用相对路径 |
| 构建失败但开发正常 | 先看 prebuild 的内容校验输出,再看 Nuxt 构建日志 |
边界
- 本文假设 Node 24 和 npm;使用其他版本时,先确认 Nuxt 和内容校验脚本兼容。
- 不启动
backend/时,AI 入口即使出现也不可用;博客的页面、接口和构建不依赖它。 npm run preview只模拟生产产物,不包含 Caddy、TLS、域名和进程管理。- 当前没有分页、搜索和增量构建;内容量变大后,开发服务器的全量读取会变慢。
- 生产镜像、反向代理和 CI 的细节在本系列的 08 构建与交付,以及 构建实践 系列里。
下一篇进入内容层:看 content.ts 怎样把 Markdown 变成经过校验的结构化数据。