VitePress静态网站从零搭建到GitHub Pages部署一站式指南和DeepWiki：AI 驱动的下一代代码知识平台

[VitePress 静态网站搭建指南](#VitePress 静态网站搭建指南)
- [🚀 环境准备与项目初始化](#🚀 环境准备与项目初始化)
- - 系统要求
  - 创建项目
- [⚙️ VitePress 初始化配置详解](#⚙️ VitePress 初始化配置详解)
- - 配置选项说明
  - 初始化后的项目结构
  - 配置文件
  - [生成的 npm 脚本在`package.json` 中](#生成的 npm 脚本在package.json 中)
- [🛠️ 本地开发与内容编写](#🛠️ 本地开发与内容编写)
[部署 VitePress 站点](#部署 VitePress 站点)
- [🚀 第一步：将项目上传到 GitHub](#🚀 第一步：将项目上传到 GitHub)
- - [⚙️ 上传前的必要准备](#⚙️ 上传前的必要准备)
  - [📝 上传步骤（Git 命令行）](#📝 上传步骤（Git 命令行）)
- [🔧 第二步：本地构建与测试](#🔧 第二步：本地构建与测试)
- [📌 第三步：设定 public 根目录](#📌 第三步：设定 public 根目录)
- [🚀 第四步：使用 GitHub Pages 自动部署](#🚀 第四步：使用 GitHub Pages 自动部署)
- https://qinzhengk.github.io/the-milky-way/
[🐛 常见问题与解决方案](#🐛 常见问题与解决方案)
- [1. 端口权限错误](#1. 端口权限错误)
- - [Windows 系统：](#Windows 系统：)
- [2. Node.js 版本管理](#2. Node.js 版本管理)
- - [安装 NVM](#安装 NVM)
  - 常用命令
[DeepWiki：AI 驱动的下一代代码知识平台](#DeepWiki：AI 驱动的下一代代码知识平台)
- [💡 如何选择：场景决定工具](#💡 如何选择：场景决定工具)
- 它是如何工作的？
- 主要应用场景
- 需要注意的局限性
- 如何使用与体验？
- https://zread.ai/QInzhengk/the-milky-way
[📚 学习资源](#📚 学习资源)

VitePress 静态网站搭建指南

🚀 环境准备与项目初始化

系统要求

Node.js：版本 22 或更高
包管理器：npm、yarn 或 pnpm

创建项目

bash 复制代码

# 创建项目目录
mkdir my-vitepress-site && cd my-vitepress-site

# 初始化项目并安装 VitePress
npm add -D vitepress@next

# 初始化 VitePress 配置
npx vitepress init

⚙️ VitePress 初始化配置详解

复制代码

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Where should VitePress look for your markdown files?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run pnpm run docs:dev and start writing.

配置选项说明

选项	含义	推荐设置
配置目录	VitePress 配置文件的存放位置	`./docs`（标准做法，隔离文档与代码）
文档目录	存放 Markdown 文件的目录	`./docs`（与配置放在一起，结构清晰）
站点标题	网站标题（显示在浏览器标签页）	自定义，如 `My Project`
站点描述	网站描述（用于SEO和摘要）	自定义，如 `A VitePress Site`
主题选择	选择界面主题	`Default Theme`（官方主题，专业简洁）
使用 TypeScript	是否使用 TypeScript 编写配置	`Yes`（获得更好的类型提示和自动补全）
添加 npm 脚本	在 package.json 中添加命令脚本	`Yes`（方便后续开发）
脚本前缀	为 VitePress 脚本添加前缀	`Yes`（避免与项目其他脚本冲突）
前缀名称	前缀的具体名称	`docs`（清晰明了）

初始化后的项目结构

复制代码

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js     # 核心配置文件 (TypeScript格式)
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md          # 首页内容
└─ package.json         # 包含 VitePress 相关脚本

docs 目录作为 VitePress 站点的项目根目录 。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

配置文件

配置文件 (.vitepress/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：

复制代码

export default {
  // 站点级选项
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // 主题级选项
  }
}

生成的 npm 脚本在`package.json` 中

json 复制代码

{
  "scripts": {
    "docs:dev": "vitepress dev docs",     // 启动本地开发服务器
    "docs:build": "vitepress build docs", // 构建生产静态文件
    "docs:preview": "vitepress preview docs" // 本地预览构建结果
  }
}

🛠️ 本地开发与内容编写

启动开发服务器

bash 复制代码

# 根据使用的包管理器选择相应命令
pnpm run docs:dev    # 使用 pnpm
npm run docs:dev     # 使用 npm
yarn docs:dev        # 使用 yarn

启动成功后，在浏览器中打开 http://localhost:5173 即可实时预览。

编写内容

编辑 docs/index.md 修改首页内容
创建新的 .md 文件添加更多页面
保存文件后，页面会自动热重载更新

修改配置

所有网站设置（导航栏、侧边栏、主题等）都在 docs/.vitepress/config.ts 中配置。

部署 VitePress 站点

以下指南基于一些前提：

VitePress 站点位于项目的 docs 目录中。
你使用的是默认的生成输出目录（.vitepress/dist）。
VitePress 作为本地依赖项安装在项目中，并且你已在 package.json 中设置以下脚本：
json 复制代码
```
{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}
```

🚀 第一步：将项目上传到 GitHub

在部署之前，需要先将项目上传到 GitHub 仓库。

⚙️ 上传前的必要准备

安装与配置 Git

如果尚未安装 Git，请从官网下载并安装。安装后建议配置全局用户名和邮箱：
bash 复制代码
```
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"
```
设置 SSH 密钥（推荐）

生成 SSH 密钥并添加到 GitHub，避免每次推送都输入密码：
bash 复制代码
```
ssh-keygen -t rsa
```
将 ~/.ssh/id_rsa.pub 的内容添加到 GitHub 账户的 Settings → SSH and GPG keys。

创建 .gitignore 文件

在项目根目录创建 .gitignore 文件，排除不需要上传的文件，例如：

gitignore 复制代码

# Dependencies
node_modules/
package-lock.json
yarn.lock
pnpm-lock.yaml

# Build output
docs/.vitepress/dist/
docs/.vitepress/cache/

# Environment variables
.env
.env.local

# Logs & temp files
*.log
.cache/
.DS_Store
Thumbs.db

# Editor files
.vscode/
.idea/
*.suo
*.sln
*.sw?

📝 上传步骤（Git 命令行）

步骤	命令	说明
1. 创建远程仓库	在 GitHub 点击 New repository，创建空仓库（不初始化 README）	避免后续推送冲突
2. 初始化本地仓库	`git init`	在项目根目录执行
3. 添加文件到暂存区	`git add .`	添加所有文件（或指定文件）
4. 提交到本地仓库	`git commit -m "Initial commit"`	提交说明应简洁清晰
5. 关联远程仓库	`git remote add origin https://github.com/用户名/仓库名.git`	或使用 SSH 地址
6. 推送到远程仓库	`git push -u origin master`（或 `main`）	首次推送使用 `-u` 关联分支

如果遇到推送冲突（如远程有 README 而本地没有），可先执行：
git pull --rebase origin master

然后再执行 git push -u origin master

🔧 第二步：本地构建与测试

运行以下命令构建文档：
bash 复制代码
```
npm run docs:build
```
构建完成后，在本地预览生产版本：
bash 复制代码
```
npm run docs:preview
```
服务将运行在 http://localhost:4173，用于检查构建结果是否正常。

📌 第三步：设定 public 根目录

如果站点部署在子路径（如 https://mywebsite.com/blog/），则需在 docs/.vitepress/config.mts 中设置 base 选项：

ts 复制代码

export default defineConfig({
  base: '/blog/', // 根据实际部署路径调整
})

例如：部署到 GitHub Pages 的 user.github.io/repo/，则 base 应设为 /repo/。

🚀 第四步：使用 GitHub Pages 自动部署

在项目根目录创建 .github/workflows/deploy.yml，内容如下：

yaml 复制代码

name: Deploy VitePress site to Pages

on:
  push:
    branches: [master]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci
      - name: Build with VitePress
        run: npm run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

在 GitHub 仓库设置中，进入 Settings → Pages → Build and deployment → Source ，选择 GitHub Actions。
将代码推送到 master 分支，工作流将自动构建并部署站点。

部署完成后，可通过 https://<用户名>.github.io/<仓库名>/ 访问。

https://qinzhengk.github.io/the-milky-way/

🐛 常见问题与解决方案

1. 端口权限错误

错误信息：

复制代码

listen EACCES: permission denied ::1:5173

解决方案：

Windows 系统：

bash 复制代码

# 检查端口占用情况
netstat -aon | find "5173"

# 重启 WinNAT 服务（管理员权限运行）
net stop winnat
net start winnat

2. Node.js 版本管理

使用 nvm (Node Version Manager) 管理多个 Node.js 版本：

安装 NVM

Windows ：从 nvm-windows 下载安装

常用命令

bash 复制代码

# 安装特定版本
nvm install 20.0.0

# 使用特定版本
nvm use 20.0.0

# 查看已安装版本
nvm list

# 设置默认版本
nvm alias default 20.0.0

# 卸载版本
nvm uninstall 18.0.0

DeepWiki：AI 驱动的下一代代码知识平台

DeepWiki是由Cognition Labs推出的一款AI驱动的代码知识管理平台。它旨在将GitHub等平台上的公共代码仓库，自动转化为动态、可交互的文档知识库，从根本上改变开发者阅读和理解开源项目的方式。

对比维度	Wiki (技术概念)	DeepWiki (AI工具)	Zread (AI工具)
概念本质	一种支持多人协同创作的内容管理系统或技术。	由Cognition AI推出的、基于AI的具体代码分析工具。	由智谱AI推出的、基于AI的具体代码分析工具。
核心功能	社群共同创建、编辑、链接页面，进行知识协作。	自动分析代码，生成交互式文档、架构图，提供AI助手解答代码问题。	自动分析代码，生成结构化文档，提供AI问答，并整合社区洞察。
内容来源	完全由用户手动创建和贡献。	自动解析GitHub等平台上的源代码。	自动解析GitHub等平台上的源代码，并整合社区信息。
技术侧重	协作与版本控制。	代码的"硬核"技术解析（如架构图、API）。	代码分析 + 项目"软性"信息（如社区动态、团队背景）。
语言与受众	全球各语种用户，广泛的知识协作者。	以英文界面为主，面向全球开发者。	重点支持中文，主要面向中文开发者。
典型代表/使用	维基百科、公司内部Wiki（如Confluence）。	访问 `deepwiki.com` 或替换GitHub链接使用。	访问 `zread.ai` 或替换GitHub链接使用。

💡 如何选择：场景决定工具

需要构建团队知识库或查阅百科 ：应使用Wiki技术（例如部署MediaWiki、使用Notion/语雀等现代Wiki工具）。
需要快速理解一个GitHub开源项目 ：
- 如果主要关注技术架构、流程图，或习惯英文界面 ，可优先尝试 DeepWiki。
- 如果需要中文界面和支持，或想同时了解项目的社区热度、口碑 ，可优先尝试 Zread。

它是如何工作的？

DeepWiki的技术架构主要基于以下三个部分：

代码理解引擎：依托其核心产品Devin AI的能力，通过分析抽象语法树（AST）和符号表，深度解析超过20种主流编程语言的代码逻辑、依赖关系和配置。
智能问答系统 ：采用检索增强生成（RAG） 技术。当用户提问时，系统会先从代码库的向量数据库中检索相关上下文，再结合大模型生成精准答案，并注明引用来源，有效减少"幻觉"。
云端处理 ：在云端高性能集群上，它已经处理了超过40亿行代码，能够快速为海量开源项目建立索引。

主要应用场景

快速上手新项目：无论是研究新技术栈还是接手遗留系统，都可以在几分钟内通过对话和图表掌握项目架构，显著缩短学习曲线。
深度代码分析与审计：AI助手可以协助定位性能瓶颈、分析潜在的安全漏洞（如SQL注入风险），或识别重复代码块，帮助进行技术债治理。
企业知识管理与培训：对于企业，它可以（通过付费或开源方案）用于构建内部私有代码库的知识库，极大提升新员工培训和技术传承的效率。

需要注意的局限性

目前，DeepWiki也存在一些局限性：

复杂代码理解可能不准：对于高度抽象或非常规的代码逻辑，AI可能产生误解，生成的内容仍需人工核实。
功能范围有限 ：目前主要分析代码本身，暂不支持对GitHub Issues、Pull Requests等协作内容的检索和分析。
私有化部署方案 ：官方的DeepWiki主要面向公共仓库。如果需要对私有代码库进行类似处理，需要关注其企业版，或者使用社区开源方案 DeepWiki-Open 进行本地化部署。

如何使用与体验？

使用DeepWiki极其简单，完全免费：

主要方式 ：将任何GitHub公共仓库的URL中的 github.com 直接替换为 deepwiki.com 并访问即可（国内可能限制生成索引）。
- 例如：https://github.com/facebook/react → https://deepwiki.com/facebook/react
备用方式 ：直接访问其官网 https://deepwiki.com，在搜索框中输入项目名称或链接。

如果你想在保护代码安全的前提下（如在公司内网）体验类似功能，可以关注GitHub上的开源项目 DeepWiki-Open，它提供了私有化部署的路径。

VitePress静态网站从零搭建到GitHub Pages部署一站式指南和DeepWiki：AI 驱动的下一代代码知识平台

VitePress静态网站从零搭建到GitHub Pages部署一站式指南和DeepWiki：AI 驱动的下一代代码知识平台

VitePress 静态网站搭建指南

🚀 环境准备与项目初始化

系统要求

创建项目

⚙️ VitePress 初始化配置详解

配置选项说明

初始化后的项目结构

配置文件

生成的 npm 脚本在package.json 中

🛠️ 本地开发与内容编写

启动开发服务器

编写内容

修改配置

部署 VitePress 站点

🚀 第一步：将项目上传到 GitHub

⚙️ 上传前的必要准备

📝 上传步骤（Git 命令行）

🔧 第二步：本地构建与测试

📌 第三步：设定 public 根目录

🚀 第四步：使用 GitHub Pages 自动部署

https://qinzhengk.github.io/the-milky-way/

🐛 常见问题与解决方案

1. 端口权限错误

Windows 系统：

2. Node.js 版本管理

安装 NVM

常用命令

DeepWiki：AI 驱动的下一代代码知识平台

💡 如何选择：场景决定工具

它是如何工作的？

主要应用场景

需要注意的局限性

如何使用与体验？

https://zread.ai/QInzhengk/the-milky-way

📚 学习资源

生成的 npm 脚本在`package.json` 中