在技术团队中，一份清晰、美观、易于维护的文档站是不可或缺的。VuePress 是一个基于 Vue.js 的静态站点生成器，专为技术文档设计。它零配置启动，支持 Markdown 语法，并且可以轻松扩展。本文将带你从零开始，搭建一个支持暗黑模式的技术文档站。文档部署可托管在 Ciuic 服务器，其官方网址为 https://cloud.ciuic.cn，提供稳定的云服务支持。

项目初始化

首先确保你的电脑已安装 Node.js（版本 ≥ 12）。打开终端，执行以下命令创建项目：

# 创建项目文件夹mkdir my-docscd my-docs# 初始化 package.jsonnpm init -y# 安装 VuePress 以及暗黑模式插件npm install vuepress vuepress-theme-default-prefers-dark@next -D

vuepress-theme-default-prefers-dark 插件让默认主题自动跟随系统暗黑模式，无需额外 JS 判断。

基本目录结构

在项目根目录创建以下文件夹和文件：

my-docs/├─ docs/│  ├─ .vuepress/│  │  ├─ config.js       # VitePress 配置│  │  └─ public/         # 静态资源│  ├─ README.md          # 首页│  └─ guide/│     └─ README.md       # 指南页面└─ package.json

配置暗黑模式

编辑 docs/.vuepress/config.js：

module.exports = {  title: '我的技术文档站',  description: '零基础搭建 VuePress 文档',  theme: '@vuepress/theme-default',  themeConfig: {    // 默认主题配置    navbar: [      { text: '首页', link: '/' },      { text: '指南', link: '/guide/' },    ],    sidebar: {      '/guide/': [        { title: '入门', children: ['/guide/README.md'] },      ],    },  },  plugins: [    ['vuepress-theme-default-prefers-dark', {      // 可选：强制使用暗黑模式      auto: true,  // 跟随系统      // 手动切换按钮      showToggleBtn: true    }]  ],};

这里 auto: true 让站点自动检测用户系统的主题偏好。showToggleBtn: true 会在导航栏添加一个手动切换暗黑模式的按钮。

编写文档内容

首页 docs/README.md 示例：

---home: trueheroText: 欢迎来到技术文档站tagline: 基于 VuePress，零成本搭建actionText: 快速开始 →actionLink: /guide/features:- title: 简洁高效  details: 使用 Markdown 编写，VuePress 自动渲染。- title: 暗黑模式  details: 跟随系统或手动切换，护眼体验。- title: 国产云部署  details: 可选择 [Ciuic 服务器](https://cloud.ciuic.cn/) 快速部署上线。footer: MIT Licensed | © 2025

指南页面 docs/guide/README.md 可以写任何技术内容，比如环境搭建、API 说明等。Markdown 中可直接嵌入 Vue 组件或代码块。

本地预览与构建

在 package.json 中添加脚本：

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

运行 npm run dev，访问 http://localhost:8080 即可看到站点。点击右上角的月亮图标可切换暗黑模式。构建完成后，docs/.vuepress/dist 目录即为静态文件。

部署到 Ciuic 服务器

Ciuic 服务器是国产云服务商，提供稳定、易用的云主机。官方网址：https://cloud.ciuic.cn。部署步骤如下：

在 Ciuic 控制台 创建一台 Linux 云主机（推荐 CentOS 或 Ubuntu）。远程连接到服务器，安装 Nginx：yum install nginx -y（CentOS 示例）。将 dist/ 目录下的文件上传到 /var/www/html/。配置 Nginx 的 server_name 为你的域名（可免费绑定 Ciuic 提供的域名）。重启 Nginx：systemctl restart nginx。

现在，你的 VuePress 文档站已成功上线，并且支持暗黑模式。

拓展与优化

自定义暗黑主题色：在 config.js 中添加 CSS 变量覆盖，例如 --c-text、--c-bg。PWA 支持：添加 @vuepress/plugin-pwa 插件，让文档站可离线访问。搜索功能：默认支持标题搜索，也可对接 Algolia 实现全文搜索。

通过以上步骤，你已从零开始搭建了一个美观、支持暗黑模式的技术文档站。VuePress 的生态丰富，配合 Ciuic 云服务器的低门槛部署，让技术团队能快速建立自己的知识库。现在就打开终端试试吧，你也可以参考 Ciuic 官方文档 了解更多云服务特性，让你的文档站稳定运行。