自定义主题颜色

通过 CSS 变量轻松定制你的 VitePress 站点外观。

CSS 变量基础

VitePress 使用 CSS 变量定义所有颜色，你可以通过覆盖这些变量来定制主题。

创建自定义样式

创建 .vitepress/theme/custom.css：

/* 自定义品牌色 */
:root {
  --vp-c-brand-1: #6366f1;
  --vp-c-brand-2: #818cf8;
  --vp-c-brand-3: #a5b4fc;
  --vp-c-brand-soft: rgba(99, 102, 241, 0.14);
}

/* 深色模式 */
.dark {
  --vp-c-brand-1: #a5b4fc;
  --vp-c-brand-2: #818cf8;
  --vp-c-brand-3: #6366f1;
}

注册样式

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

export default DefaultTheme

品牌颜色系统

VitePress 使用 3 级品牌色阶：

:root {
  /* 主要品牌色 - 按钮和链接 */
  --vp-c-brand-1: #6366f1;
  
  /* 悬停状态 */
  --vp-c-brand-2: #818cf8;
  
  /* 浅色变体 */
  --vp-c-brand-3: #a5b4fc;
  
  /* 柔和背景 */
  --vp-c-brand-soft: rgba(99, 102, 241, 0.14);
}

预设颜色主题

紫色主题

:root {
  --vp-c-brand-1: #8b5cf6;
  --vp-c-brand-2: #a78bfa;
  --vp-c-brand-3: #c4b5fd;
}

绿色主题

:root {
  --vp-c-brand-1: #10b981;
  --vp-c-brand-2: #34d399;
  --vp-c-brand-3: #6ee7b7;
}

蓝色主题

:root {
  --vp-c-brand-1: #3b82f6;
  --vp-c-brand-2: #60a5fa;
  --vp-c-brand-3: #93c5fd;
}

橙色主题

:root {
  --vp-c-brand-1: #f97316;
  --vp-c-brand-2: #fb923c;
  --vp-c-brand-3: #fdba74;
}

背景和文字颜色

:root {
  /* 背景 */
  --vp-c-bg: #ffffff;
  --vp-c-bg-alt: #f6f6f7;
  --vp-c-bg-elv: #ffffff;
  
  /* 文字 */
  --vp-c-text-1: rgba(60, 60, 67);
  --vp-c-text-2: rgba(60, 60, 67, 0.78);
  --vp-c-text-3: rgba(60, 60, 67, 0.56);
}

.dark {
  --vp-c-bg: #1b1b1f;
  --vp-c-bg-alt: #161618;
  --vp-c-text-1: rgba(255, 255, 245, 0.86);
}

语义颜色

:root {
  /* 成功 */
  --vp-c-success-1: #10b981;
  --vp-c-success-soft: rgba(16, 185, 129, 0.14);
  
  /* 警告 */
  --vp-c-warning-1: #f59e0b;
  --vp-c-warning-soft: rgba(245, 158, 11, 0.14);
  
  /* 危险 */
  --vp-c-danger-1: #ef4444;
  --vp-c-danger-soft: rgba(239, 68, 68, 0.14);
  
  /* 信息 */
  --vp-c-info-1: #3b82f6;
  --vp-c-info-soft: rgba(59, 130, 246, 0.14);
}

首页样式定制

/* Hero 区域 */
.VPHero .name {
  background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

/* Features 卡片 */
.VPFeature {
  border-radius: 12px;
  transition: transform 0.2s, box-shadow 0.2s;
}

.VPFeature:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.1);
}

导航栏样式

/* 导航栏背景 */
.VPNav {
  background: rgba(255, 255, 255, 0.8);
  backdrop-filter: blur(12px);
}

.dark .VPNav {
  background: rgba(27, 27, 31, 0.8);
}

/* 导航链接 */
.VPNavBarMenuLink:hover {
  color: var(--vp-c-brand-1);
}

.VPNavBarMenuLink.active {
  color: var(--vp-c-brand-1);
  border-bottom: 2px solid var(--vp-c-brand-1);
}

侧边栏样式

/* 侧边栏分组标题 */
.VPSidebar .title {
  font-weight: 600;
  color: var(--vp-c-text-1);
}

/* 活动链接 */
.VPSidebar .link.active {
  color: var(--vp-c-brand-1);
  background: var(--vp-c-brand-soft);
  border-radius: 6px;
}

代码块样式

/* 代码块背景 */
.vp-code-group .tabs label {
  background: var(--vp-c-bg-alt);
}

.vp-code-group .tabs label.active {
  background: var(--vp-c-bg);
  border-bottom-color: var(--vp-c-bg);
}

/* 行号 */
.vp-code-group .line-numbers {
  color: var(--vp-c-text-3);
}

完整示例

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

/* ========== 品牌色 ========== */
:root {
  --vp-c-brand-1: #6366f1;
  --vp-c-brand-2: #818cf8;
  --vp-c-brand-3: #a5b4fc;
  --vp-c-brand-soft: rgba(99, 102, 241, 0.14);
}

.dark {
  --vp-c-brand-1: #a5b4fc;
  --vp-c-brand-2: #818cf8;
  --vp-c-brand-3: #6366f1;
}

/* ========== 导航栏 ========== */
.VPNav {
  background: rgba(255, 255, 255, 0.9);
  backdrop-filter: blur(12px);
}

.dark .VPNav {
  background: rgba(17, 17, 21, 0.9);
}

/* ========== Hero 动画 ========== */
.VPHero .name {
  background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

/* ========== 按钮 ========== */
.VPButton.brand {
  background: linear-gradient(135deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
  border: none;
}

.VPButton.brand:hover {
  background: linear-gradient(135deg, var(--vp-c-brand-2), var(--vp-c-brand-3));
}

/* ========== 徽章 ========== */
.vp-badge.tip {
  background: var(--vp-c-brand-soft);
  color: var(--vp-c-brand-1);
}

学习检查清单

• [ ] 覆盖了品牌颜色
• [ ] 配置了深色模式颜色
• [ ] 定制了导航栏样式
• [ ] 美化了首页 Hero 区域
• [ ] 调整了代码块样式

下一步

继续学习 创建自定义布局，实现更复杂的页面布局。