Next.js Blog Project - Quick Start

Next.js 博客项目 - 快速开始

Project Template Selection

项目模板选择

推荐使用官方模板： Recommended official template:

这是一个功能完整、设计精美的 Next.js 博客模板，基于以下技术栈： This is a fully-featured, beautifully designed Next.js blog template based on the following tech stack:

Next.js 15 - React 框架
Next.js 15 - React framework
Tailwind CSS - 实用优先的 CSS 框架
Tailwind CSS - Utility-first CSS framework
Contentlayer - MDX 内容管理
Contentlayer - MDX content management
TypeScript - 类型安全
TypeScript - Type safety
Framer Motion - 动画效果
Framer Motion - Animation effects

1. 环境配置 | 1. Environment Configuration

1.1 安装 Node.js | Install Node.js

访问 Node.js 官网下载并安装对应系统版本。 Visit Node.js official website to download and install the version for your system.

版本要求：Node.js ^20.0.0 Version requirement: Node.js ^20.0.0

1.2 克隆项目 | Clone Project

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

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

1.3 依赖安装 | Install Dependencies

npm install
# 或
# or
yarn install

1.4 开发工具推荐 | Recommended Development Tools

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

Tool Name	Type	Description
VSCode	Free	Recommended to install Tailwind CSS IntelliSense plugin
WebStorm	Paid	JetBrains all-in-one IDE
Cursor	Free/Paid	AI-assisted programming tool

1.5 环境变量配置 | Environment Variables Configuration

创建 .env.local 文件（可选）： Create .env.local file (optional):

# 基础路径（如果部署在子目录）
# Base path (if deploying in subdirectory)
BASE_PATH=

# 分析工具 ID（如 Umami）
# Analytics tool ID (e.g., Umami)
NEXT_UMAMI_ID=

# Giscus 评论系统（可选）
# Giscus comment system (optional)
NEXT_PUBLIC_GISCUS_REPO=
NEXT_PUBLIC_GISCUS_REPOSITORY_ID=
NEXT_PUBLIC_GISCUS_CATEGORY=
NEXT_PUBLIC_GISCUS_CATEGORY_ID=

# 其他环境变量...
# Other environment variables...

2. 项目文件配置 | 2. Project File Configuration

2.1 核心配置文件结构 | Core Configuration File Structure

├── data/
│ ├── siteMetadata.js # 网站元数据配置
│ │ # Website metadata configuration
│ ├── authors/
│ │ └── default.mdx # 作者信息
│ │ # Author information
│ ├── projectsData.js # 项目展示数据
│ │ # Project showcase data
│ ├── headerNavLinks.js # 导航菜单配置
│ │ # Navigation menu configuration
│ └── blog/ # 博客文章目录
│ # Blog articles directory
├── public/
│ └── static/ # 静态资源（图片、logo 等）
│ # Static assets (images, logos, etc.)
├── components/ # React 组件
│ # React components
├── layouts/ # 页面布局组件
│ # Page layout components
├── app/ # Next.js App Router 页面
│ # Next.js App Router pages
├── next.config.js # Next.js 配置
│ # Next.js configuration
├── tailwind.config.js # Tailwind CSS 配置
│ # Tailwind CSS configuration
└── contentlayer.config.ts # Contentlayer 配置
│ # Contentlayer configuration

2.2 网站元数据配置 | Website Metadata Configuration

文件路径：data/siteMetadata.js File path: data/siteMetadata.js

这是最重要的配置文件，包含网站的所有基本信息： This is the most important configuration file containing all basic website information:

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

  // 主题设置
  // Theme settings
  theme: 'system', // system, dark or light

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

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

  // 社交媒体链接（不需要的可以注释掉）
  // Social media links (comment out unwanted ones)
  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',

  // 其他配置
  // Other configuration
  locale: 'zh-CN',
  stickyNav: false, // 是否固定导航栏
  // Whether to fix navigation bar

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

  // 评论系统（可选）
  // Comment system (optional)
  comments: {
    provider: 'giscus',
    giscusConfig: {
      repo: process.env.NEXT_PUBLIC_GISCUS_REPO,
      // ... 其他配置
      // Other configuration
    },
  },

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

2.3 作者信息配置 | Author Information Configuration

文件路径：data/authors/default.mdx File path: data/authors/default.mdx

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

# Your name

# Avatar

# Your occupation

# Your company

# Email

# GitHub

# 个人简介

# Personal Introduction

在这里写你的个人简介，支持 Markdown 和 React 组件。
Write your personal introduction here, supports Markdown and React components.

2.4 导航菜单配置 | Navigation Menu Configuration

文件路径：data/headerNavLinks.js File path: data/headerNavLinks.js

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

2.5 项目展示配置 | Project Showcase Configuration

文件路径：data/projectsData.js File path: data/projectsData.js

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

3. Next.js 配置 | 3. Next.js Configuration

3.1 基础配置 | Basic Configuration

文件路径：next.config.js File path: next.config.js

主要配置项包括： Main configuration items include:

图片优化：配置远程图片域名
Image optimization: Configure remote image domains
安全头部：CSP、HSTS 等安全策略
Security headers: CSP, HSTS and other security policies
Server Actions：允许的源地址
Server Actions: Allowed source addresses
构建优化：导出模式、图片格式等
Build optimization: Export mode, image formats, etc.

3.2 图片域名配置 | Image Domain Configuration

如果需要在文章中使用外部图片，需要在 next.config.js 中配置： If you need to use external images in articles, configure in next.config.js:

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

4. 启动项目 | 4. Start Project

4.1 开发模式 | Development Mode

npm run dev
# 或
# or
yarn dev

访问 http://localhost:3000 查看效果。 Visit http://localhost:3000 to view the result.

4.2 生产构建 | Production Build

npm run build
# 或
# or
yarn build

4.3 启动生产服务器 | Start Production Server

npm run serve
# 或
# or
yarn serve

5. 撰写博客 | 5. Writing Blog

5.1 创建博客文章 | Create Blog Article

在 data/blog 目录下创建 .mdx 文件： Create .mdx file in data/blog directory:

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

# Article Title

# Publish date

# Tags

# Draft status

# Article summary, will appear in list page

# 文章内容

# Article Content

在这里使用 Markdown 语法撰写文章内容。
Write article content using Markdown syntax here.

## 代码示例

## Code Example

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

支持的功能 | Supported Features

代码高亮：使用 Prism.js
Code highlighting: Using Prism.js
数学公式：支持 KaTeX
Math formulas: Support KaTeX
图片：支持本地和远程图片
Images: Support local and remote images
表格：标准 Markdown 表格
Tables: Standard Markdown tables
引用：支持 GitHub 风格的警告框
Quotes: Support GitHub-style alert boxes

5.2 Frontmatter 配置说明 | Frontmatter Configuration Description

| 字段 | 说明 | 必填 |

Field	Description	Required
title	文章标题	是
title	Article title	Yes
date	发布日期	是
date	Publish date	Yes
tags	标签数组	否
tags	Tag array	No
draft	是否为草稿	否（默认 false）
draft	Is draft	No (default false)
summary	文章摘要	否
summary	Article summary	No
layout	布局类型	否（默认 PostLayout）
layout	Layout type	No (default PostLayout)

5.3 支持的布局类型 | Supported Layout Types

PostLayout - 默认两栏布局（左侧内容，右侧目录）
PostLayout - Default two-column layout (content left, TOC right)
PostSimple - 简化版布局
PostSimple - Simplified layout
PostBanner - 带横幅图片的布局
PostBanner - Layout with banner image

5.4 文章分类 | Article Classification

可以在 data/blog 下创建子目录来分类文章： You can create subdirectories under data/blog to classify articles:

data/
└── blog/
├── 教学/
├── Teaching/
├── 技术/
├── Technology/
├── 生活/
├── Life/
└── Uncategorized/

6. 自定义样式 | 6. Custom Styles

6.1 Tailwind CSS 配置 | Tailwind CSS Configuration

文件路径：tailwind.config.js File path: tailwind.config.js

可以自定义颜色、字体、间距等： You can customize colors, fonts, spacing, etc.:

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

6.2 代码高亮主题 | Code Highlighting Theme

文件路径：css/prism.css File path: css/prism.css

替换为喜欢的 PrismJS 主题，或自定义样式。 Replace with your favorite PrismJS theme or customize styles.

6.3 全局样式 | Global Styles

文件路径：css/tailwind.css File path: css/tailwind.css

添加自定义全局样式。 Add custom global styles.

7. 部署 | 7. Deployment

7.1 Vercel 部署（推荐）| Vercel Deployment (Recommended)

将代码推送到 GitHub
Push code to GitHub
在 Vercel 导入项目
Import project on Vercel
配置环境变量
Configure environment variables
自动部署
Automatic deployment

7.2 其他平台 | Other Platforms

Netlify：支持 Git 集成
Netlify: Supports Git integration
GitHub Pages：需要配置输出模式
GitHub Pages: Requires output mode configuration
自托管：使用 Docker 或 Node.js
Self-hosted: Use Docker or Node.js

7.3 环境变量 | Environment Variables

在部署平台配置以下环境变量： Configure the following environment variables on deployment platform:

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

8. 常见问题 | 8. Common Issues

8.1 图片不显示 | Images Not Displaying

检查图片路径是否正确
Check if image path is correct
确认远程域名已在 next.config.js 中配置
Confirm remote domain is configured in next.config.js
本地图片放在 public/static 目录
Put local images in public/static directory

8.2 样式不生效 | Styles Not Taking Effect

清除 .next 缓存目录
Clear .next cache directory
重新运行 npm run dev
Re-run npm run dev
检查 Tailwind 配置
Check Tailwind configuration

8.3 构建失败 | Build Failure

检查 Node.js 版本是否符合要求
Check if Node.js version meets requirements
删除 node_modules 和 yarn.lock 重新安装
Delete node_modules and yarn.lock and reinstall
查看错误日志定位问题
Check error logs to locate the issue

9. 进阶功能 | 9. Advanced Features

9.1 自定义组件 | Custom Components

在 components/MDXComponents.tsx 中添加自定义组件，可在 MDX 文件中使用： Add custom components in components/MDXComponents.tsx that can be used in MDX files:

import CustomComponent from './CustomComponent'

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

9.2 添加页面 | Add Pages

在 app/ 目录下创建新的页面路由： Create new page routes in app/ directory:

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

9.3 集成第三方服务 | Integrate Third-Party Services

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

10. 参考资源 | 10. Reference Resources

总结 | Summary

通过以上步骤，你已经成功搭建了一个功能完整的 Next.js 博客。现在可以： Through the above steps, you have successfully built a fully functional Next.js blog. Now you can:

✅ 自定义网站信息
✅ Customize website information
✅ 撰写和发布博客文章
✅ Write and publish blog articles
✅ 配置导航和项目展示
✅ Configure navigation and project showcase
✅ 自定义样式和主题
✅ Customize styles and themes
✅ 部署到生产环境
✅ Deploy to production environment

接下来可以探索更多高级功能，如添加评论系统、集成分析工具、优化 SEO 等。祝你在博客写作之旅中收获满满！ Next, you can explore more advanced features such as adding comment systems, integrating analytics tools, optimizing SEO, etc. Wish you a fruitful blogging journey!