个人博客自建指南（5）：VitePress 主题微调 —— 让博客更像你的

前言

第4篇我们把 VitePress 跑起来了，默认主题干净、好用，但毕竟是“默认”的——每个 VitePress 博客都长这样。如果你想让博客有点自己的味道，换换颜色、字体、Logo，这篇就是为你准备的。

本篇全是“配置级”操作，不动 Vue 组件，不写 TypeScript 逻辑，改完立竿见影。

一、关于 TypeScript 与类型声明

本博客项目使用了 TypeScript，它能在编写代码时提供类型检查和智能提示。但 TypeScript 默认不认识 .css 、.svg 等非代码文件，因此当你执行 import './custom.css' 时，VSCode 会显示红色波浪线，提示“找不到模块”。
这不影响运行 —— VitePress 在构建时会正确处理这些导入。

如果你觉得红波浪线碍眼，可以通过以下配置一次性消除。

1.1 确认项目结构

确保你的项目根目录（jiejinx-blog/）下有以下文件：

jiejinx-blog/
├── docs/
│   ├── .vitepress/
│   │   └── theme/
│   │       ├── index.ts
│   │       └── custom.css
│   ├── index.md
├── package.json
├── tsconfig.json          ← 根目录，管理整个项目 （若没有则新建）
└── env.d.ts               ← 类型声明文件（若没有则新建）

1.2 配置 tsconfig.json

打开根目录的 tsconfig.json，确保内容如下：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["vitepress"],
    "skipLibCheck": true
  },
  "include": [
    "docs/.vitepress/**/*",
    "docs/**/*.md",
    "env.d.ts"
  ]
}

为什么用 types: ["vitepress"]？
你的项目直接依赖是 vitepress。TypeScript 通过 types 配置加载类型时，会去 node_modules/vitepress下找类型定义。而 VitePress 的类型定义内部已经通过 /// <reference types="vite/client" /> 引用了 vite/client，所以 TypeScript 会沿着这条链自动加载 vite 的类型。
这样你既获得了 VitePress 的类型支持，也间接获得了 vite/client的支持，无需手动指定 vite/client。

1.3 创建 env.d.ts

在根目录下新建 env.d.ts（如果已有则直接编辑），写入以下内容：

declare module '*.css' {
  const content: string
  export default content
}

这段代码告诉 TypeScript：所有以 .css 结尾的文件都是一个合法的模块，默认导出一个字符串。保存后，VSCode 会自动重新加载配置，红色波浪线立即消失。

如果你以后还导入了 .svg、.png等文件，可以继续在 env.d.ts中添加类似的后缀声明。

1.4 完成

以上两步配置好后，整个项目中的 TypeScript 报错都会被消除。后续所有“配置级”操作（换色、改字体、加 Logo 等）都不会再被 VSCode 的红色波浪线干扰。

二、换品牌色

VitePress 默认的品牌色是 Vue 绿（#42b883），通过 CSS 变量控制。 在 .vitepress/theme/下新建一个 custom.css：

/* .vitepress/theme/custom.css */

/* 亮色模式 */
:root {
  --vp-c-brand-1: #ff0080;
  --vp-c-brand-2: #ff66b3;
  --vp-c-brand-3: #ff99cc;
  --vp-c-brand-soft: rgba(255, 0, 128, 0.16);
}

/* 暗黑模式 */
.dark {
  --vp-c-brand-1: #ff4da6;
  --vp-c-brand-2: #ff80bf;
  --vp-c-brand-3: #ffb3d9;
  --vp-c-brand-soft: rgba(255, 77, 166, 0.24);
}

在 .vitepress/theme/ 下新建一个 index.ts 作为主题入口，加载 custom.css：

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

💡 如果 VSCode 在 import './custom.css' 下显示红色波浪线，请先完成本章第 一节“关于 TypeScript 与类型声明”的配置，之后再也不会出现此类误报。

改完运行 pnpm run dev ，刷新浏览器就能看到品牌色变了（导航栏图标、链接文字、按钮背景从绿色变为粉红色）。

三、换中文字体

Windows 下默认字体在生僻字场景会崩，换成系统自带的中文字体更稳。在 custom.css 中追加：

:root {
  --vp-font-family-base: 'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
  --vp-font-family-mono: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
}

• --vp-font-family-base：正文和标题字体
• --vp-font-family-mono：代码块字体

如果你安装了 JetBrains Mono 或 Fira Code，代码块会很好看；没装的话 fallback 到 Consolas，也不丑。

四、首页 Logo 和站点名

VitePress 支持两种方式设置左上角的 Logo：图片文件​ 或 Base64 编码。

方式一：使用图片文件

将一张方形图片（推荐 SVG 或 PNG，200×200 以内）放到 docs/public/logo.svg，然后在 config.ts 中配置：

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: '阶进遐',
    // ... 其他配置
  }
})

• logo：左上角显示的小图标，路径相对于 public/ 目录。
• siteTitle：Logo 旁边的文字，如果不设则默认显示 title 的值。
• 如果不想显示站点名，只留 Logo，可以设 siteTitle: false。

方式二：使用 Base64 编码（无需图片文件）

直接将图片转为 Base64 字符串嵌入配置，适合小尺寸图标（如 SVG 或 32×32 PNG）。示例：

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0MCIgaGVpZ2h0PSI0MCIgdmlld0JveD0iMCAwIDQwIDQwIj48cGF0aCBkPSJNMjAgMzBhMTAgMTAgMCAxIDEgMC0yMCAxMCAxMCAwIDAgMSAwIDIweiIgZmlsbD0iI2ZmMDA4MCIvPjwvc3ZnPg==',
    siteTitle: '阶进遐',
    // ... 其他配置
  }
})

💡 说明：上面示例是一个 40×40 的纯粉色圆形 SVG 图标（Base64 编码）。你可以用在线工具（如 Base64.Guru）将自己的 Logo 图片转为 Base64 字符串替换进去。注意 Base64 字符串较长，建议在配置中单独定义一个常量存放，保持文件整洁。

五、首页 Hero 区域微调

第4篇的首页 docs/index.md 只配了 hero.name 和 hero.text，还可以加更多：

---
layout: home

hero:
  name: "阶进遐的技术随笔"
  text: "编程经验分享 · 树莓派自建服务器 · 私有云架构实践"
  tagline: 从零搭建，每一步决策都记录。
  image:
    src: data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI4MCIgaGVpZ2h0PSI4MCIgdmlld0JveD0iMCAwIDgwIDgwIj48Y2lyY2xlIGN4PSI0MCIgY3k9IjQwIiByPSIzMCIgZmlsbD0iI2ZmMDA4MCIvPjwvc3ZnPg==
    alt: logo
  actions:
    - theme: brand
      text: 开始阅读
      link: /guide/md-demo
    - theme: alt
      text: 关于我
      link: /about

features:
  - icon: 🌲
    title: 树莓派专栏
    details: 7 篇主线 + 7 篇番外，从家宽 IPv6 到 ECS 双轨反代。
  - icon: 🛠️
    title: 博客自建
    details: fnm / Vite / pnpm / Git，从零搭起这个博客。
  - icon: ☁️
    title: 私有云架构
    details: 后续规划：Docker 化、算力节点、音乐 App。
---

• actions：首页按钮，可以放两个（主要操作 + 次要操作）
• features：首页下方的特性展示，三列布局，适合放专栏简介或站点亮点

六、导航栏和页脚

导航栏可以加更多链接，页脚可以加备案号和版权信息：

// docs/.vitepress/config.ts

themeConfig: {
   // ... 其他配置

  //顶部导航
  nav: [
    { text: '首页', link: '/' },
    { text: '博客', link: '/guide/my-first-post' },
    { text: '关于', link: '/about' },
    {
      text: '更多',
      items: [
        { text: '树莓派专栏', link: 'https://pi.jiejinx.cn' },
        { text: 'GitHub', link: 'https://github.com/你的用户名' },
      ]
    }
  ],
  
  //页脚
  footer: {
    message: '<a href="https://beian.miit.gov.cn" target="_blank" rel="noopener noreferrer">新ICP备19xxxxx号-1</a>',
    copyright: '阶进遐 © 2026'
  },

  //社交链接
  socialLinks: [
    { icon: 'github', link: 'https://github.com/你的用户名' },
  ],
}

说明：

• footer.message 中的 <a> 标签会直接渲染为可点击的备案链接，点击后跳转到工信部备案查询官网。
• 如果你还有其他备案信息（如公安备案），可以用 <span> 或 <br> 分隔，继续追加 HTML。
• 请将 你的用户名 替换为真实的 GitHub 用户名，并将备案号替换为你自己的备案号。
• 导航栏支持下拉菜单（items 数组），适合放外部链接或分类入口。

七、启用本地搜索

VitePress 默认使用 Algolia 搜索（需要申请 API Key），个人博客用本地搜索就够了：

// docs/.vitepress/config.ts

themeConfig: {
     // ... 其他配置
    
    // 文章搜索配置
    search: {
      provider: 'local',
      // 核心：通过 locales 配置中文界面
      options: {
        locales: {
          // 重点：单语言中文站点必须用 root 作为键名
          root: {
            translations: {
              button: {
                buttonText: '搜索',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                displayDetails: '显示详细列表',
                resetButtonTitle: '重置搜索',
                backButtonTitle: '关闭搜索',
                noResultsText: '没有结果',
                footer: {
                  selectText: '选择',
                  selectKeyAriaLabel: '回车',
                  navigateText: '切换',
                  navigateUpKeyAriaLabel: '上箭头',
                  navigateDownKeyAriaLabel: '下箭头',
                  closeText: '关闭',
                  closeKeyAriaLabel: 'Esc'
                }
              }
            }
          }
        }
      }
    },
}

启用后，导航栏会出现搜索框，读者可以全文搜索你的博客文章，不需要任何外部服务。

八、文章导览

默认的文章内部 导览 是英文的， 可配置成中文。

// docs/.vitepress/config.ts

themeConfig: {
     // ... 其他配置

    // 文章内部导航配置
    docFooter: {
      prev: '上一篇',
      next: '下一篇'
    },
    outline: {
      label: '本页目录'
    },
    returnToTopLabel: '返回顶部',
    sidebarMenuLabel: '总目录',
    darkModeSwitchLabel: '主题',
    lightModeSwitchTitle: '切换到亮色模式',
    darkModeSwitchTitle: '切换到暗色模式',
}

九、404 错误页

默认的文章内部 404页面 是英文的， 可配置成中文。
在 config.ts 的 themeConfig 中加 notFound 字段：

// docs/.vitepress/config.ts

themeConfig: {
    // ... 其他配置

    // 404配置
    notFound: {
      title: '页面未找到',
      quote: '但如果你不改变方向，并且继续寻找，你可能最终会到达你所前往的地方。',
      linkText: '返回首页',
      linkLabel: '带我回首页',
      code: '404'
    },
}

十、更深度的定制（进阶）

以上都是“配置级”操作，不改 Vue 组件。如果你对 Vue 3 熟悉，还可以：

• 自定义 Layout 组件：在 .vitepress/theme/index.ts 中继承默认主题，在特定插槽插入自己的内容（比如首页 hero 下方加一个“最新文章”列表）
• 自定义 404 页面组件：同样 自定义 Layout 组件 ，构建 404 页面布局。
• 自定义代码块样式：通过 CSS 变量 --vp-code-line-height、--vp-code-font-size 等微调代码块外观

但这些超出了“主题微调”的范畴，属于“主题开发”，本专栏不展开。有兴趣的读者可以查阅 VitePress 官方文档的 自定义主题 | VitePress 章节。

总结

这篇我们做了：

1. 换品牌色（CSS 变量）
2. 换中文字体和代码字体
3. 加 Logo 和站点名
4. 丰富首页 Hero 区域
5. 配置导航栏、页脚、社交链接
6. 启用本地搜索
7. 文章导览配置中文说明
8. 404页面配置中文说明

改完这些，你的博客就有了自己的视觉风格，不再是千篇一律的默认主题了。
而且所有这些改动都是“配置级”的，不需要写 Vue 组件，改完保存，浏览器自动刷新就能看到效果。