vitepress-theme-ninc

VitePress Theme Ninc

一个功能丰富的 VitePress 主题 — 开箱即用的博客、文档与工具站。
配好就能跑，想改哪里就改哪里。

使用文档 · 在线演示 · 问题反馈 · 更新日志

为什么造这个轮子

用 VitePress 搭文档的人不少，但是搭建博客的人却寥寥无几，毕竟默认主题太素了。市面上的主题要么功能略有残缺，要么改起来费劲。我想要的是一个零基础可配置装上就能用、不用折腾插件的主题。

这个主题基于 imsyy/vitepress-theme-curve 二次开发。curve 的底子很好，我在此基础上做了大量重构和扩展：抽成 npm 包、重写配置系统、梳理使用文档、以及加了大量功能和样式，让它真正能开箱即用。

三分钟上手

# 用脚手架创建项目（推荐）
npx vitepress-theme-ninc init

# 跟着提示走：填站点名、选极简 or 完整配置
# 完事之后：
cd your-blog && pnpm install && pnpm dev

打开 http://localhost:5173，博客跑起来了。想改配置？看 使用文档，每个字段都有截图和说明。

内置的功能

界面预览

文章页 & 关于页

归档页 & 评论页

页脚 & 装备页

手动安装

不想用脚手架也行，在现有的 VitePress 项目中安装：

pnpm add vitepress-theme-ninc
# 或
npm install vitepress-theme-ninc
# 或
yarn add vitepress-theme-ninc

.vitepress/theme/index.ts：

import Theme from 'vitepress-theme-ninc'
export default Theme

.vitepress/config.mts：

import { defineConfig } from 'vitepress-theme-ninc/defineConfig'
import { themeConfig } from './themeConfig'

export default defineConfig(
  { sitemap: { hostname: 'https://your-site.com' } },
  themeConfig,
)

.vitepress/themeConfig.ts（最小配置）：

import { defineThemeConfig } from 'vitepress-theme-ninc/defineThemeConfig'

export const themeConfig = defineThemeConfig({
  siteMeta: {
    title: 'My Blog',
    description: 'powered by ninc',
    site: 'https://example.com',
    avatar: '/images/avatar.png',
    lang: 'zh-CN',
    author: {
      name: 'Your Name',
      email: 'you@example.com'
    }
  }
})

写一篇文章（posts/hello.md）：

---
title: Hello World
tags: [随笔]
categories: [公告]
date: 2026-07-09
description: 我的第一篇文章
---

# Hello World

这是使用 vitepress-theme-ninc 搭建的博客的第一篇文章。

CLI 命令

主题自带三个命令行工具：

后两条也可在 init 生成的项目里通过 pnpm run summary / pnpm run init-proxy 调用。完整用法见 CLI 文档。

包导出

环境要求

• Node.js >= 20
• pnpm >= 9（推荐，npm/yarn 也行）
• VitePress ^1.6.4
• Vue ^3.5.0

文档

完整文档在 theme.ninc.top：

• 使用指南 — 从安装到部署的完整流程
• 配置参考 — 所有配置项的字段说明
• 组件总览 — 内置组件一览
• FAQ — 常见问题与坑

想看实际效果，作者博客 就是这个主题在跑。

技术架构

几个关键决定：

• 客户端源码直发 + Node 侧预构建：客户端（.vue / store / styles）不预构建，VitePress 在用户项目通过 Vite 处理 .ts / .vue；Node 侧工厂函数（defineConfig / defineThemeConfig / utils / node）由 scripts/build-node.mjs 预构建为 dist/*.js，保证在纯 Node 环境（配置文件、CLI）可直接运行。
• defu 深合并：用 defu 替代 Object.assign，嵌套配置不会被整体覆盖，用户只填想改的字段就行。
• 双工厂函数：defineConfig 管 VitePress 配置，defineThemeConfig 管主题配置，两边解耦。
• patch-package：对 nes-vue 的运行时补丁通过 postinstall 自动应用，安装即可使用 NES 模拟器。

反馈与贡献

遇到问题：

• 先翻 FAQ 和 Issues
• 没找到答案就提个 Issue，贴上复现步骤和配置文件

欢迎 PR，大的改动建议先开 Issue 讨论一下方向再动手。

致谢

• VitePress — 底层框架
• imsyy/vitepress-theme-curve — 本主题的前身，感谢 imsyy 的开源
• Twikoo — 评论系统
• APlayer — 音乐播放器
• nes-vue — NES 模拟器组件

License

MIT © 2023-present 呢喃Ninc