跳到主要内容
Ed. notes

03 从零跑起来:目录、依赖与命令

长文 · 2026-11-12 · 合集第 4 / 10 篇

  • 上手
  • npm
  • Nuxt
  • 构建日志
第 4 / 10 篇 · 查看全部章节 → 当前: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。

验证

第一次上手,按这个顺序验收:

  1. npm run content:validate 通过;
  2. npm run dev 后首页、目录、详情都能打开;
  3. 新增一篇 draft: true 的笔记,刷新 /notes,确认它没有出现;
  4. 删掉这篇测试笔记,再跑一次校验;
  5. 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 变成经过校验的结构化数据。