第三部分：本地开发

3.1 启动开发服务器

npm run dev

访问 http://localhost:3000 查看效果。

3.2 热重载

Next.js 支持热重载，修改以下内容会自动刷新：

  • TypeScript/React 组件
  • Markdown 文章
  • CSS 样式

注意：修改环境变量后需重启开发服务器。

3.3 内容目录结构

整个 content/ 目录是博客的数据中心，支持两种使用形式：

  • Git 子模块（默认）：每个文件夹独立成仓，方便多设备同步和协作
  • 普通文件夹：直接创建文件夹即可，无需 Git 子模块配置

完整结构

content/
├── posts/              # 博客文章（子模块）
│   ├── article-slug/
│   │   ├── index.md    # 文章正文（frontmatter + markdown）
│   │   └── assets/     # 文章用到的图片/资源
│   └── ...
├── docs/               # 文档集（子模块）
│   ├── meta.json       # 文档集元数据（标题、描述、图标、排序）
│   ├── collection-a/   # 文档集合（如 cacatheory, deployment）
│   │   ├── meta.json   # 集合配置（标题、描述、图标、排序、发布状态）
│   │   ├── p1.md       # 文档页面
│   │   ├── p2.md
│   │   └── summary.md  # 总结/汇总
│   └── ...
├── moments/            # 日常动态（子模块）
│   ├── 202605181511/
│   │   ├── index.md    # 动态正文
│   │   └── photos/     # 照片资源
│   └── ...
├── demos/              # 交互式演示（子模块）
│   ├── demo-name/
│   │   ├── meta.json   # 标题、描述、标签、发布状态
│   │   ├── demo.html   # 完整 HTML 演示文件
│   │   └── ...         # 其他资源（JS/CSS/图片）
│   └── ...
└── spec/               # 静态单页面（子模块）
    ├── about/          # 关于页面
    │   └── index.md
    ├── projects/       # 项目展示
    │   └── index.md
    ├── information/    # 信息页面
    │   └── index.md
    └── journey/        # 历程页面
        └── index.md

说明：

  • 所有内容使用 Markdown 编写，放在对应分类的文件夹中
  • 路径必须使用英文小写 + 连字符，禁止空格和非 ASCII 字符
  • 图片等资源放在该内容的 assets/ 或 photos/ 目录中，使用相对路径引用
  • 每个内容文件夹下的 index.md 是正文入口
  • 子模块与普通文件夹在使用上完全一致，区别仅在于 Git 的版本管理方式

使用子模块

项目默认配置为 5 个独立的子模块仓库：

# 首次克隆后初始化子模块
git submodule update --init --recursive

# 或在 clone 时一并拉取
git clone --recurse-submodules <repo-url>

每个子模块可独立管理版本：

cd content/posts
git add .
git commit -m "new post"
git push

不使用子模块（纯文件夹）

如果不需要独立版本控制，直接删除 .gitmodules 和对应 .git 目录即可转为普通文件夹：

# 删除子模块配置
git rm --cached content/posts
git rm --cached content/docs
git rm --cached content/moments
git rm --cached content/demos
git rm --cached content/spec
rm .gitmodules
rm -rf content/posts/.git content/docs/.git content/moments/.git content/demos/.git content/spec/.git

# 重新添加到主仓库
git add content/
git commit -m "convert submodules to plain folders"

3.4 文章创作

创建新文章

  1. 在 content/posts/ 下创建文件夹
  2. 文件夹内创建 index.md
  3. 编写文章内容

目录结构：

content/posts/article-slug/
├── index.md
└── assets/
    └── image.jpg

文章格式

---
title: 文章标题
published: 2026-04-14
description: 文章摘要
category: 分类
tags: [标签1, 标签2]
draft: false
---

# 文章内容

![图片](/docs/deployment/./assets/image.jpg)

Frontmatter 字段说明

字段 类型 说明
title string 文章标题
published string 发布日期
description string 文章摘要
category string 分类
tags array 标签数组
draft boolean 是否为草稿

3.5 Demo 创作

创建 Demo

  1. 在 content/demos/ 下创建文件夹
  2. 创建 meta.json 和 demo.html
  3. 添加资源文件（可选）

meta.json 格式：

{
  "title": "Demo 标题",
  "description": "Demo 描述",
  "tags": ["标签1"],
  "author": "作者",
  "date": "2026-04-14",
  "published": true
}

3.6 调试

浏览器开发者工具

  • Console: 查看 JavaScript 错误和日志
  • Elements: 检查 DOM 和 CSS
  • Network: 查看网络请求

日志输出

console.log("调试信息", data);

React DevTools

安装浏览器扩展以调试 React 组件。