NJCodeX

主题

📅 2026-07-19⏱️ 约 10 分钟实战VitePressNginx

从零搭建个人博客：VitePress + Nginx 完全指南 ​

本文记录了搭建本站点（njcodex.com）的完整过程，从零开始，包含所有踩坑记录。

为什么选择 VitePress？ ​

在搭建个人博客之前，我对比了几个主流方案：

方案优点缺点
WordPress功能强大，插件丰富需要数据库，较重
Hexo中文社区活跃构建速度一般
Hugo构建极快模板语法学习成本
VitePress极快、Vue 生态、Markdown需要一定前端基础

最终选择 VitePress 的理由：

  • 🚀 基于 Vite，构建速度极快
  • 📝 原生支持 Markdown，写作体验好
  • 🎨 默认主题就很美观
  • 🔧 高度可定制

环境准备 ​

服务器配置 ​

  • 操作系统：Linux (Debian/Ubuntu)
  • Web 服务器：Nginx 1.26+
  • Node.js：v24.x
  • 域名：njcodex.com

检查环境 ​

bash
# 检查 Node.js
node -v  # 需要 v18+

# 检查 Nginx
nginx -v

# 检查 certbot（用于 HTTPS）
certbot --version

第一步：创建项目 ​

bash
# 创建项目目录
mkdir -p /www/blog && cd /www/blog

# 初始化 npm 项目
npm init -y

# 安装 VitePress
npm add -D vitepress

第二步：创建项目结构 ​

bash
# 创建目录结构
mkdir -p docs/.vitepress
mkdir -p docs/public
mkdir -p docs/notes

最终目录结构：

/www/blog/
├── docs/
│   ├── .vitepress/
│   │   └── config.mts       # VitePress 配置
│   ├── public/
│   │   └── logo.svg         # 网站 Logo
│   ├── notes/
│   │   └── index.md         # 笔记列表页
│   ├── about.md             # 关于我
│   └── index.md             # 首页
├── package.json
└── node_modules/

第三步：配置 VitePress ​

创建 docs/.vitepress/config.mts：

typescript
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: "NJCodeX",
  description: "记录学习与成长",
  lang: 'zh-CN',
  
  head: [
    ['link', { rel: 'icon', href: '/logo.svg' }],
    // SEO 相关
    ['meta', { property: 'og:title', content: 'NJCodeX' }],
    ['meta', { property: 'og:description', content: '编程笔记、AI 工具' }],
  ],

  themeConfig: {
    logo: '/logo.svg',
    
    nav: [
      { text: '🏠 首页', link: '/' },
      { text: '📝 笔记', link: '/notes/' },
      { text: '👤 关于', link: '/about' }
    ],

    sidebar: {
      '/notes/': [
        { text: '📋 总览', link: '/notes/' },
        {
          text: '🤖 Claude Code',
          items: [
            { text: '快速入门', link: '/notes/claude-code-quickstart' },
            { text: '快捷键参考', link: '/notes/claude-code-shortcuts' },
          ]
        }
      ]
    },

    search: {
      provider: 'local'  // 本地搜索
    },

    footer: {
      message: '用代码记录成长 🚀',
      copyright: '© 2026 NJCodeX'
    }
  }
})

第四步：创建首页 ​

创建 docs/index.md：

markdown
---
layout: home

hero:
  name: "NJCodeX"
  text: "记录学习与成长"
  tagline: "每一次学习，都是一次蜕变 🚀"
  image:
    src: /logo.svg
    alt: Logo
  actions:
    - theme: brand
      text: 📚 开始阅读
      link: /notes/

features:
  - icon: 🤖
    title: Claude Code
    details: AI 编程助手的快速入门指南
  - icon: ✍️
    title: 提示词工程
    details: 掌握 AI 提示词技巧
---

第五步：构建与预览 ​

bash
# 添加构建脚本到 package.json
# "scripts": {
#   "docs:dev": "vitepress dev docs",
#   "docs:build": "vitepress build docs",
#   "docs:preview": "vitepress preview docs"
# }

# 构建静态文件
npm run docs:build

# 本地预览
npm run docs:preview

构建完成后，静态文件会输出到 docs/.vitepress/dist/ 目录。

第六步：配置 Nginx ​

创建 Nginx 配置文件 /etc/nginx/sites-available/njcodex.com：

nginx
# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name njcodex.com www.njcodex.com;
    return 301 https://$host$request_uri;
}

# HTTPS
server {
    listen 4443 ssl;  # 注意：如果用了 stream 层 SNI 分流
    server_name njcodex.com www.njcodex.com;
    
    root /www/blog/docs/.vitepress/dist;
    index index.html;
    
    ssl_certificate /etc/letsencrypt/live/njcodex.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/njcodex.com/privkey.pem;
    
    location / {
        try_files $uri $uri/ $uri.html /index.html;
    }
    
    # 缓存静态资源
    location ~* \.(js|css|png|jpg|gif|ico|svg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    # gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;
}

启用配置 ​

bash
# 创建软链接
ln -sf /etc/nginx/sites-available/njcodex.com /etc/nginx/sites-enabled/

# 测试配置
nginx -t

# 重载 Nginx
systemctl reload nginx

第七步：申请 HTTPS 证书 ​

bash
# 使用 certbot 申请 Let's Encrypt 证书
certbot certonly --nginx \
  -d njcodex.com \
  -d www.njcodex.com \
  --non-interactive \
  --agree-tos \
  --email admin@njcodex.com

证书会自动续期，无需手动操作。

第八步：配置 DNS ​

在域名注册商处添加 DNS 记录：

类型名称值
A@你的服务器 IP
Awww你的服务器 IP

等待 DNS 生效（通常几分钟到几小时）。

⚠️ 踩坑记录 ​

坑 1：Nginx stream 层 SNI 分流 ​

如果服务器上有其他服务也使用 443 端口（如 Docker 里的 DERP），需要在 nginx.conf 的 stream 块中添加域名分流规则：

nginx
stream {
    map $ssl_preread_server_name $backend_name {
        sub.289111.xyz   web_https;
        njcodex.com      web_https;      # 添加这行
        www.njcodex.com  web_https;      # 添加这行
        default          derp_https;
    }
    
    upstream web_https {
        server 127.0.0.1:4443;  # 指向 Nginx HTTPS
    }
}

然后把博客的 server block 改为监听 4443 端口。

坑 2：VitePress 死链接检查 ​

构建时如果报 Found dead link，说明有链接指向不存在的页面。检查：

  • 链接路径是否正确
  • 文件是否在正确的位置

坑 3：DNS 解析延迟 ​

修改 DNS 后，可能需要等待几分钟到几小时才能生效。可以用以下命令检查：

bash
# 检查 DNS 解析
dig +short njcodex.com A

# 检查全球 DNS 生效情况
# 访问 https://dnschecker.org/

第九步：发布文章 ​

bash
# 创建新文章
cat > docs/notes/my-first-post.md << 'EOF'
---
title: 我的第一篇文章
date: 2026-07-19
tags: [入门]
---

# 我的第一篇文章

这是我的第一篇博客文章！

## 内容

写点什么...
EOF

# 重新构建
npm run docs:build

总结 ​

整个搭建过程大约 30 分钟，主要步骤：

  1. ✅ 安装 VitePress
  2. ✅ 创建项目结构
  3. ✅ 配置主题和导航
  4. ✅ 配置 Nginx
  5. ✅ 申请 HTTPS 证书
  6. ✅ 配置 DNS
  7. ✅ 发布文章

技术栈：

  • VitePress（静态站点生成）
  • Nginx（Web 服务器）
  • Let's Encrypt（HTTPS 证书）

成本：

  • 服务器：已有
  • 域名：已有
  • HTTPS：免费（Let's Encrypt）
  • 总成本：0 元

如果你也想搭建个人博客，可以按照本文的步骤操作。有问题欢迎留言交流！

用代码记录成长 · RSS 订阅 · 标签

© 2026 NJCodeX · Powered by VitePress