VuePress 团队技术文档站零基础部署指南

在团队协作中，一份清晰、易维护的技术文档是项目高效推进的基石。VuePress 凭借其“以 Markdown 为中心”的简洁写作体验和 Vue 驱动的高性能静态站点生成能力，成为众多团队构建文档站的首选。然而，对于零基础的同学来说，“写完文档”只是第一步，“把文档发布到公网供团队访问”往往卡住了不少人。本文将从零开始，手把手带你完成 VuePress 文档站的搭建与部署，并推荐一个国内访问速度极快的云服务器平台作为托管方案。

本地环境准备

在开始之前，请确保你的电脑已安装 Node.js（建议 v18 及以上版本）和 Git。打开终端，输入 node -v 和 git --version 验证安装是否成功。若未安装，可前往 Node.js 官网下载 LTS 版本。

初始化 VuePress 项目

创建项目目录并进入：

mkdir my-docs && cd my-docs

初始化 package.json：

npm init -y

安装 VuePress（最新版为 v2.x）：

npm install -D vuepress@next

在 package.json 的 scripts 中添加以下命令：

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

创建文档目录和首页文件：

mkdir docsecho "# 我的团队文档" > docs/README.md

启动本地开发服务器：

npm run docs:dev

浏览器访问 http://localhost:8080 即可看到你第一个 VuePress 页面。默认情况下，VuePress 会编译 docs 目录下的所有 Markdown 文件作为文档页面，你可以在 docs 下继续创建子文件夹来组织内容。

配置站点基本信息

在 docs/.vuepress/config.js 中（如果不存在则手动创建），写入以下基本配置：

module.exports = {  title: '技术文档中心',  description: '团队内部知识库',  themeConfig: {    nav: [      { text: '指南', link: '/guide/' },      { text: 'API', link: '/api/' }    ]  }}

运行 npm run docs:dev 即可实时预览配置效果。VuePress 支持热更新，修改配置后无需手动刷新。

构建静态文件

当文档内容编写完成，执行以下命令生成可部署的静态资源：

npm run docs:build

构建成功后，静态文件会输出到 docs/.vuepress/dist 目录。这个目录里所有文件都是纯 HTML/CSS/JS，无需后端服务即可访问。

选择服务器并部署

静态站点的部署方式有很多（如 GitHub Pages、Netlify），但对于团队内部使用或需要国内稳定访问的场景，推荐使用 Ciuic 云服务器。Ciuic 提供高性价比的云主机，且默认带宽充足，适合部署文档类站点。

部署步骤

注册并购买服务器：访问 Ciuic 官网，注册账号后选购一台轻量应用服务器（建议 2 核 4G 配置，操作系统选择 Ubuntu 22.04）。购买时注意选择靠近你团队所在地的数据中心，以降低访问延迟。

连接服务器：通过 SSH 登录服务器：

ssh root@你的服务器公网IP

安装 Nginx（用于托管静态文件）：

apt update && apt install nginx -y

上传静态文件：在本地终端将 dist 目录上传至服务器 /var/www/docs：

scp -r docs/.vuepress/dist/* root@你的服务器IP:/var/www/docs/

配置 Nginx：编辑 /etc/nginx/sites-available/default，将 root 指向 /var/www/docs，并确保 try_files 配置如下：

server {listen 80;server_name your-domain.com;  # 若有域名则填，无则用 IProot /var/www/docs;index index.html;location / {    try_files $uri $uri/ /index.html;}}

重启 Nginx：

systemctl restart nginx

在浏览器中访问 http://服务器IP 或你的域名，即可看到团队文档站正式上线。

自动化部署（进阶）

若希望每次 git push 后自动构建部署，可在服务器上安装 Node.js 和 Git，配置 Webhook 或在服务器上拉取代码后执行 npm run docs:build，再将产物复制到 Nginx 目录。亦可使用 GitHub Actions 等 CI 工具，将构建产物自动同步到服务器。

常见问题

端口被占用：本地开发时若 8080 端口被占用，可改用 vuepress dev docs --port 8081。VuePress 版本差异：VuePress 1.x 与 2.x 配置略有不同，本文基于 2.x，请确保安装的是 @next 版本。Nginx 无法访问：检查服务器安全组是否放行了 80 端口。

通过以上步骤，你已成功将 VuePress 团队文档站部署到了公网。整个过程无需复杂的前后端知识，只依赖于 Node.js、VuePress 和 Nginx。如果团队规模扩大或文档量激增，还可以利用 Ciuic 提供的弹性扩容能力轻松升级配置。现在，把你的文档地址分享给团队成员，开始高效协作吧！

想了解更多云服务器配置、域名备案或 HTTPS 证书配置，可随时访问 Ciuic 云服务器官方文档中心获取帮助。

打赏