vitepress-theme-ninc
v1.0.40
Published
A feature-rich VitePress theme by ninc - blog, docs, and utilities out of the box. 功能完整的 VitePress 博客 / 文档主题，开箱即用。
Maintainers
zcxiao_Readme
为什么造这个轮子
用 VitePress 搭文档的人不少，但是搭建博客的人却寥寥无几，毕竟默认主题太素了。市面上的主题要么功能略有残缺，要么改起来费劲。我想要的是一个零基础可配置装上就能用、不用折腾插件的主题。
这个主题基于 imsyy/vitepress-theme-curve 二次开发。curve 的底子很好，我在此基础上做了大量重构和扩展：抽成 npm 包、重写配置系统、梳理使用文档、以及加了大量功能和样式，让它真正能开箱即用。
三分钟上手
# 用脚手架创建项目（推荐）
npx vitepress-theme-ninc init
# 跟着提示走：填站点名、选极简 or 完整配置
# 完事之后：
cd your-blog && pnpm install && pnpm dev打开 http://localhost:5173，博客跑起来了。想改配置？看 使用文档，每个字段都有截图和说明。
内置的功能
| | | |---|---| | 评论系统 | Twikoo，支持表情、图片、邮件通知 | | 全站搜索 | Algolia DocSearch + 本地搜索双模式 | | 音乐播放器 | APlayer + MetingJS，挂网易云平台歌单 | | AI 文章摘要 | 接入 OpenAI 兼容 API，构建时自动生成摘要 | | 文章加密 | 密码保护指定文章，HMAC-SHA256 | | PWA 离线 | 自动生成 Service Worker，断网也能看 | | 图片灯箱 | Fancybox，点击放大、缩放、拖拽 | | RSS 订阅 | 构建时自动生成 rss.xml | | 暗色模式 | 跟随系统 + 手动切换，View Transitions 动画 | | NES 模拟器 | 内置红白机模拟器页面，init 自带超级马里奥（对，真的能玩） | | 代码组图标 | 按语言自动配图标 | | 外链中转 | 自动转换外链为中转页跳转，保护隐私、提升 SEO | | 装备编年史 | 数据可视化页面，ECharts 驱动 | | 等等等... | 更多功能请看 使用文档 |
- 首页 Banner + 波浪动画 + 技能图标墙
- 打赏按钮（微信 / 支付宝二维码）
- 不蒜子访问量 / 访客数 / 文章阅读量
- 自定义鼠标光标、Mac 风格卡片、Safari 模拟器
- Lottie / GSAP / 三维粒子背景
- SVG 雪碧图、Gzip + Brotli 压缩
- Vue API 与组件全自动导入
- 组件 Demo 插件、代码定位（Alt+Shift 点击跳源码）
- TypeScript 类型完备，配置项有完整提示
更多功能请看 使用文档
界面预览
文章页 & 关于页
归档页 & 评论页
页脚 & 装备页
手动安装
不想用脚手架也行，在现有的 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: '[email protected]'
}
}
})写一篇文章（posts/hello.md）：
---
title: Hello World
tags: [随笔]
categories: [公告]
date: 2026-07-09
description: 我的第一篇文章
---
# Hello World
这是使用 vitepress-theme-ninc 搭建的博客的第一篇文章。CLI 命令
主题自带三个命令行工具：
| 命令 | 干什么 |
| --- | --- |
| npx vitepress-theme-ninc init | 从零生成一个完整的博客项目 |
| npx vitepress-theme-ninc summary | 本地预生成 AI 摘要到缓存文件 |
| npx vitepress-theme-ninc init-proxy | 生成 AI 摘要运行时代理脚手架（Cloudflare / Vercel） |
后两条也可在 init 生成的项目里通过 pnpm run summary / pnpm run init-proxy 调用。完整用法见 CLI 文档。
包导出
| 子路径 | 用途 |
| --- | --- |
| vitepress-theme-ninc | 主题入口（默认导出 Theme 对象） |
| vitepress-theme-ninc/defineConfig | VitePress 配置工厂 |
| vitepress-theme-ninc/defineThemeConfig | 主题配置工厂（defu 深合并） |
| vitepress-theme-ninc/node | Node 侧工具聚合 |
| vitepress-theme-ninc/utils | Node 侧 utils（getAllPosts 等） |
| vitepress-theme-ninc/views | 客户端视图组件（NesGame 等） |
| vitepress-theme-ninc/components | 客户端组件 |
| vitepress-theme-ninc/store | Pinia store |
| vitepress-theme-ninc/styles | 全局样式入口（scss） |
| vitepress-theme-ninc/types | TypeScript 类型声明 |
环境要求
- Node.js >= 20
- pnpm >= 9（推荐，npm/yarn 也行）
- VitePress ^1.6.4
- Vue ^3.5.0
文档
完整文档在 theme.ninc.top：
想看实际效果，作者博客 就是这个主题在跑。
技术架构
几个关键决定：
- 直接发布源码：不预构建，VitePress 在用户项目通过 Vite 处理
.ts / .mjs / .vue。主题入口面向 VitePress / Vite 构建链，不支持在纯 Node.js 20 里直接执行源码。 - defu 深合并：用
defu替代Object.assign，嵌套配置不会被整体覆盖，用户只填想改的字段就行。 - 双工厂函数：
defineConfig管 VitePress 配置，defineThemeConfig管主题配置，两边解耦。 - patch-package：对
nes-vue的运行时补丁通过postinstall自动应用，安装即可使用 NES 模拟器。
反馈与贡献
遇到问题：
欢迎 PR，大的改动建议先开 Issue 讨论一下方向再动手。
致谢
- VitePress — 底层框架
- imsyy/vitepress-theme-curve — 本主题的前身，感谢 imsyy 的开源
- Twikoo — 评论系统
- APlayer — 音乐播放器
- nes-vue — NES 模拟器组件