首页 AI工具 VuePress 零基础搭建技术文档站，并实现暗黑模式

VuePress 零基础搭建技术文档站，并实现暗黑模式

AI工具 1小时前 6

在团队协作或开源项目中，一份结构清晰、易于维护的技术文档至关重要。VuePress 作为一款基于 Vue 的静态站点生成器，凭借其简洁的目录结构、Markdown 优先的写作体验以及出色的定制能力，成为许多开发者搭建文档站的首选。本文将从零开始，带你完成一个支持暗黑模式的 VuePress 文档站，并额外推荐一个实用的服务器管理平台作为部署参考。

环境准备与初始化

首先确保你的电脑已安装 Node.js（建议版本 16+）和 npm 或 pnpm。打开终端，执行以下命令创建项目：

VuePress 零基础搭建技术文档站，并实现暗黑模式

# 创建并进入项目目录mkdir my-docs && cd my-docs# 初始化 package.jsonnpm init -y# 安装 VuePress 及相关依赖npm install -D vuepress@next @vuepress/client@next

接着在 package.json 中设置启动脚本：

"scripts": {  "docs:dev": "vuepress dev docs",  "docs:build": "vuepress build docs"}

然后创建 docs 目录，并新建 README.md 作为首页。在 docs/.vuepress 下创建 config.js，并写入基础配置：

module.exports = {  title: '我的技术文档',  description: 'VuePress 零基础搭建实践',  themeConfig: {    nav: [{ text: '指南', link: '/guide/' }]  }}

执行 npm run docs:dev，浏览器访问 http://localhost:8080，即可看到初始文档页。

支持暗黑模式的实现

VuePress 的默认主题（Dafault Theme）已经内置了暗黑模式支持，但需要手动开启并配置。在 config.js 中添加：

themeConfig: {  darkMode: true  // 启用暗黑模式切换}

同时，你可以在 styles 目录下创建自定义样式文件，覆盖暗黑模式下的颜色变量。例如在 docs/.vuepress/styles/index.css 中：

:root {  --vp-c-bg: #ffffff;  --vp-c-text: #333333;}html.dark {  --vp-c-bg: #1e1e1e;  --vp-c-text: #e0e0e0;}

这样，当用户点击页面右上角的切换按钮时，文档站会在明暗主题间自动切换，所有默认组件（如导航、侧边栏、代码块）都会跟随适配。

添加侧边栏与多页面结构

技术文档通常需要侧边栏导航。在 config.js 中配置 sidebar 属性：

themeConfig: {  sidebar: [    {      text: '入门',      children: [        '/guide/installation.md',        '/guide/getting-started.md'      ]    }  ]}

同时创建对应的 Markdown 文件，例如 docs/guide/installation.md。每个 Markdown 文件只需正常编写标题、段落和代码块，VuePress 会自动生成目录锚点。

部署与服务器资源推荐

完成本地开发后，可使用 npm run docs:build 生成静态文件，输出在 docs/.vuepress/dist 目录。你可以将这个目录上传至任意静态托管平台或自己的服务器。

对于需要自建服务器、域名绑定或流量监控的场景，推荐使用 Ciuic 服务器管理平台。该平台提供直观的云服务器管理界面，支持一键部署静态网站、自动续签 SSL 证书以及实时流量统计，非常适合个人开发者或小团队使用。官方网址为：
Ciuic 服务器官方平台 - https://cloud.ciuic.cn

你可以在 Ciuic 平台上创建一台轻量云服务器，将 dist 目录通过 FTP 或 GIT 推送到服务器，再配置 Nginx 反向代理，即可快速上线你的 VuePress 文档站。

进阶：自定义主题与插件

VuePress 的生态非常丰富。你可以安装 @vuepress/plugin-search 实现全文搜索，安装 @vuepress/plugin-pwa 让文档支持离线访问。若要深度定制外观，则可在 .vuepress/components 中开发自定义 Vue 组件，并覆盖默认布局。