Next.js 博客项目 - 快速起步

项目模板选用

推荐使用官方模板： tailwind-nextjs-starter-blog

这是一个功能完整、设计精美的 Next.js 博客模板，基于以下技术栈：

Next.js 15 - React 框架
Tailwind CSS - 实用优先的 CSS 框架
Contentlayer - MDX 内容管理
TypeScript - 类型安全
Framer Motion - 动画效果

1. 环境配置

1.1 安装 Node.js

访问 Node.js 官网下载并安装对应系统版本。

版本要求：Node.js ^20.0.0

1.2 克隆项目

# 使用 git clone
git clone https://github.com/timlrx/tailwind-nextjs-starter-blog.git
cd tailwind-nextjs-starter-blog

# 或者 fork 到自己的仓库后克隆
git clone https://github.com/YOUR_USERNAME/tailwind-nextjs-starter-blog.git

1.3 依赖安装

npm install
# 或
yarn install

1.4 开发工具推荐

工具名称	类型	说明
VSCode	免费	推荐安装 Tailwind CSS IntelliSense 插件
WebStorm	付费	JetBrains 全能 IDE
Cursor	免费/付费	AI 辅助编程工具

1.5 环境变量配置

创建 .env.local 文件（可选）：

# 基础路径（如果部署在子目录）
BASE_PATH=

# 分析工具 ID（如 Umami）
NEXT_UMAMI_ID=

# Giscus 评论系统（可选）
NEXT_PUBLIC_GISCUS_REPO=
NEXT_PUBLIC_GISCUS_REPOSITORY_ID=
NEXT_PUBLIC_GISCUS_CATEGORY=
NEXT_PUBLIC_GISCUS_CATEGORY_ID=

# 其他环境变量...

2. 项目文件配置

2.1 核心配置文件结构

├── data/
│ ├── siteMetadata.js # 网站元数据配置
│ ├── authors/
│ │ └── default.mdx # 作者信息
│ ├── projectsData.js # 项目展示数据
│ ├── headerNavLinks.js # 导航菜单配置
│ └── blog/ # 博客文章目录
├── public/
│ └── static/ # 静态资源（图片、logo 等）
├── components/ # React 组件
├── layouts/ # 页面布局组件
├── app/ # Next.js App Router 页面
├── next.config.js # Next.js 配置
├── tailwind.config.js # Tailwind CSS 配置
└── contentlayer.config.ts # Contentlayer 配置

2.2 网站元数据配置

文件路径：data/siteMetadata.js

这是最重要的配置文件，包含网站的所有基本信息：

const siteMetadata = {
  // 基本信息
  title: '你的博客标题',
  author: '你的名字',
  headerTitle: '网站头部标题',
  description: '网站描述',
  language: 'zh-CN',

  // 主题设置
  theme: 'system', // system, dark 或 light

  // 网站地址
  siteUrl: 'https://your-domain.com',
  siteRepo: 'https://github.com/YOUR_USERNAME/repo',

  // 资源路径
  siteLogo: '/static/images/logo.png',
  socialBanner: '/static/images/twitter-card.png',

  // 社交媒体链接（不需要的可以注释掉）
  email: 'your-email@example.com',
  github: 'https://github.com/YOUR_USERNAME',
  twitter: 'https://twitter.com/YOUR_USERNAME',
  // linkedin: 'https://linkedin.com/in/YOUR_USERNAME',
  // youtube: 'https://youtube.com/YOUR_CHANNEL',

  // 其他配置
  locale: 'zh-CN',
  stickyNav: false, // 是否固定导航栏

  // 分析工具（可选）
  analytics: {
    umamiAnalytics: {
      umamiWebsiteId: process.env.NEXT_UMAMI_ID,
    },
  },

  // 评论系统（可选）
  comments: {
    provider: 'giscus',
    giscusConfig: {
      repo: process.env.NEXT_PUBLIC_GISCUS_REPO,
      // ... 其他配置
    },
  },

  // 搜索功能
  search: {
    provider: 'kbar',
    kbarConfig: {
      searchDocumentsPath: '/search.json',
    },
  },
}

2.3 作者信息配置

文件路径：data/authors/default.mdx

---
name: 你的名字
avatar: /static/images/avatar.png
occupation: 你的职业
company: 你的公司
email: your-email@example.com
github: https://github.com/YOUR_USERNAME
---

# 个人简介

在这里写你的个人简介，支持 Markdown 和 React 组件。

2.4 导航菜单配置

文件路径：data/headerNavLinks.js

const headerNavLinks = [
  { href: '/blog', title: '博客' },
  { href: '/tags', title: '标签' },
  { href: '/projects', title: '项目' },
  { href: '/about', title: '关于' },
  // 添加更多导航链接...
]

2.5 项目展示配置

文件路径：data/projectsData.js

const projectsData = [
  {
    title: '项目名称',
    description: '项目描述',
    imgSrc: '/static/images/project-image.png',
    href: 'https://github.com/YOUR_USERNAME/project',
  },
  // 添加更多项目...
]

3. Next.js 配置

3.1 基础配置

文件路径：next.config.js

主要配置项包括：

图片优化：配置远程图片域名
安全头部：CSP、HSTS 等安全策略
Server Actions：允许的源地址
构建优化：导出模式、图片格式等

3.2 图片域名配置

如果需要在文章中使用外部图片，需要在 next.config.js 中配置：

images: {
  remotePatterns: [
    {
      protocol: 'https',
      hostname: 'example.com',
    },
    // 添加更多域名...
  ],
}

4. 启动项目

4.1 开发模式

npm run dev
# 或
yarn dev

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

4.2 生产构建

npm run build
# 或
yarn build

4.3 启动生产服务器

npm run serve
# 或
yarn serve

5. 撰写博客

5.1 创建博客文章

在 data/blog 目录下创建 .mdx 文件：

---
title: '文章标题'
date: '2025-01-20'
tags: ['tag1', 'tag2']
draft: false
summary: '文章摘要，会显示在列表页'
---

# 文章内容

在这里使用 Markdown 语法撰写文章内容。

## 代码示例

```javascript
console.log('Hello, World!')
```

支持的功能

代码高亮：使用 Prism.js
数学公式：支持 KaTeX
图片：支持本地和远程图片
表格：标准 Markdown 表格
引用：支持 GitHub 风格的警告框


### 5.2 Frontmatter 配置说明

| 字段 | 说明 | 必填 |
|-----|------|------|
| title | 文章标题 | 是 |
| date | 发布日期 | 是 |
| tags | 标签数组 | 否 |
| draft | 是否为草稿 | 否（默认 false） |
| summary | 文章摘要 | 否 |
| layout | 布局类型 | 否（默认 PostLayout） |

### 5.3 支持的布局类型

- `PostLayout` - 默认两栏布局（左侧内容，右侧目录）
- `PostSimple` - 简化版布局
- `PostBanner` - 带横幅图片的布局

### 5.4 文章分类

可以在 `data/blog` 下创建子目录来分类文章：

```markdown
data/
└── blog/
    ├── 教学/
    ├── 技术/
    ├── 生活/
    └── Uncategorized/

6. 自定义样式

6.1 Tailwind CSS 配置

文件路径：tailwind.config.js

可以自定义颜色、字体、间距等：

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#your-color',
      },
    },
  },
}

6.2 代码高亮主题

文件路径：css/prism.css

替换为喜欢的 PrismJS 主题，或自定义样式。

6.3 全局样式

文件路径：css/tailwind.css

添加自定义全局样式。

7. 部署

7.1 Vercel 部署（推荐）

将代码推送到 GitHub
在 Vercel 导入项目
配置环境变量
自动部署

7.2 其他平台

Netlify：支持 Git 集成
GitHub Pages：需要配置输出模式
自托管：使用 Docker 或 Node.js

7.3 环境变量

在部署平台配置以下环境变量：

NODE_ENV=production
BASE_PATH=
NEXT_UMAMI_ID=
# 其他需要的环境变量...

8. 常见问题

8.1 图片不显示

检查图片路径是否正确
确认远程域名已在 next.config.js 中配置
本地图片放在 public/static 目录

8.2 样式不生效

清除 .next 缓存目录
重新运行 npm run dev
检查 Tailwind 配置

8.3 构建失败

检查 Node.js 版本是否符合要求
删除 node_modules 和 yarn.lock 重新安装
查看错误日志定位问题

9. 进阶功能

9.1 自定义组件

在 components/MDXComponents.tsx 中添加自定义组件，可在 MDX 文件中使用：

import CustomComponent from './CustomComponent'

const components = {
  CustomComponent,
  // ... 其他组件
}

9.2 添加页面

在 app/ 目录下创建新的页面路由：

// app/custom-page/page.tsx
export default function CustomPage() {
  return <div>自定义页面内容</div>
}

9.3 集成第三方服务

评论系统：Giscus、Utterances、Disqus
分析工具：Umami、Google Analytics、Plausible
搜索功能：Algolia、Kbar

10. 参考资源

总结

通过以上步骤，你已经成功搭建了一个功能完整的 Next.js 博客。现在可以：

✅ 自定义网站信息
✅ 撰写和发布博客文章
✅ 配置导航和项目展示
✅ 自定义样式和主题
✅ 部署到生产环境

接下来可以探索更多高级功能，如添加评论系统、集成分析工具、优化 SEO 等。祝你在博客写作之旅中收获满满！