VitePress使用和nginx/apache配置支持简析

垣宇

已于 2025-02-25 17:35:51 修改

阅读量728

点赞数 13

分类专栏：开发框架/组件文章标签： vue.js javascript actionscript github 前端 ecmascript redmine

于 2025-02-25 07:20:03 首次发布

本文链接：https://blog.youkuaiyun.com/mycollege2011/article/details/145841372

版权

简介

VitePress 是一个静态站点生成器（SSG），专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。

安装

前置准备

Node.js 18 及以上版本。
通过命令行界面 (CLI) 访问 VitePress 的终端。
支持 Markdown 语法的编辑器。
推荐 VSCode 及其官方 Vue 扩展。

VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：

npm add -D vitepress
#
pnpm add -D vitepress
#
yarn add -D vitepress
#
yarn add -D vitepress vue
#
bun add -D vitepress

需要注意的是：

VitePress 是仅 ESM 的软件包。不要使用 require() 导入它，并确保最新的 package.json 包含 "type": "module"，或者更改相关文件的文件扩展名，例如 .vitepress/config.js 到 .mjs/.mts。更多详情请参考 Vite 故障排除指南。此外，在异步 CJS 上下文中，可以使用 await import('vitepress') 代替。

安装向导

VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：

npx vitepress init
#
pnpm vitepress init
#
yarn vitepress init
#
bun vitepress init

将需要回答几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

注意：Vue 作为 peer dependency

如果打算使用 Vue 组件或 API 进行自定义，还应该明确地将 vue 安装为 dependency。

文件结构

如果正在构建一个独立的 VitePress 站点，可以在当前目录 (./) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。

假设选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

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

注意：

默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache 中，并将生产构建输出存储在 .vitepress/dist 中。如果使用 Git，应该将它们添加到 .gitignore 文件中。也可以手动配置这些位置。

配置文件

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

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

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

实例

// .vitepress/config.js
module.exports = {
  title: '我的VitePress站点',
  description: '这是使用VitePress创建的站点',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    sidebar: {
      '/guide/': [
        {
          title: '指南',
          collapsable: false,
          children: [
            '/guide/'
          ]
        }
      ]
    }
  }
}

还可以通过 themeConfig 选项配置主题的行为。有关所有配置选项的完整详细信息，请参见配置参考。

源文件

.vitepress 目录之外的 Markdown 文件被视为源文件。

VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。

VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。这些可以参考路由指南。

启动运行

该工具还应该将以下 npm 脚本注入到 package.json 中：

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

npm run docs:dev
#
pnpm run docs:dev
#
yarn docs:dev
#
bun run docs:dev

除了 npm 脚本，还可以直接调用 VitePress：

npx vitepress dev docs
#
pnpm vitepress dev docs
#
yarn vitepress dev docs
#
bun vitepress dev docs

更多的命令行用法请参见 CLI 参考。

开发服务应该会运行在 http://localhost:5173 上。在浏览器中访问 URL 以查看新站点的运行情况。

构建站点

运行命令构建站点

示例

npx vitepress build .vitepress

使用场景

文档

VitePress 附带一个专为技术文档设计的默认主题。你VitePress以及 Vite、Rollup、Pinia、VueUse、Vitest、D3、UnoCSS、Iconify 等文档都是基于这个主题的。

Vue.js 官方文档也是基于 VitePress 的。但是为了可以在不同的翻译文档之间切换，它自定义了自己的主题。

博客、档案和营销网站

VitePress 支持完全的自定义主题，具有标准 Vite + Vue 应用程序的开发体验。基于 Vite 构建还意味着可以直接利用其生态系统中丰富的 Vite 插件。此外，VitePress 提供了灵活的 API 来加载数据 (本地或远程)，也可以动态生成路由。只要可以在构建时确定数据，就可以使用它来构建几乎任何东西。

Vue.js 官方博客是一个简单的博客页面，它根据本地内容生成其索引页面。

特点

VitePress 旨在使用 Markdown 生成内容时提供出色的开发体验。其工作原理如下：

Vite 驱动：即时服务器启动，始终立即反映 (<100ms) 编辑变化，无需重新加载页面。

内置 Markdown 扩展：frontmatter、表格、语法高亮……应有尽有。具体来说，VitePress 提供了许多用于处理代码块的高级功能，使其真正成为技术文档的理想选择。

Vue 增强的 Markdown：每个 Markdown 页面都是 Vue 单文件组件，这要归功于 Vue 模板与 HTML 的 100% 语法兼容性。可以使用 Vue 模板语法或导入的 Vue 组件在静态内容中嵌入交互性。

性能

与许多传统的 SSG 不同，每次导航都会导致页面完全重新加载，VitePress 生成的网站在初次访问时提供静态 HTML，但它变成了单页应用程序（SPA）进行站点内的后续导航。我们认为，这种模式为性能提供了最佳平衡：

快速的初始加载

对任何页面的初次访问都将会是静态的、预呈现的 HTML，以实现极快的加载速度和最佳的 SEO。然后页面加载一个 JavaScript bundle，将页面变成 Vue SPA (这被称为“激活”)。与 SPA 激活缓慢的常见假设不同，由于 Vue 3 良好的原始性能和编译优化，这个过程实际上非常快。

在 PageSpeed Insights 上，典型的 VitePress 站点即使在网络速度较慢的低端移动设备上也能获得近乎完美的性能分数。

加载完成后可以快速切换

更重要的是，SPA 模型在首次加载后能够提升用户体验。用户在站点内导航时，不会再触发整个页面的刷新。而是通过获取并动态更新页面的内容来实现切换。

VitePress 还会自动预加载视口范围内链接对应的页面片段。这样一来，大部分情况下，用户在加载完成后就能立即浏览新页面。

高效的交互

为了能够嵌入静态 Markdown 中的动态 Vue 部分，每个 Markdown 页面都被处理为 Vue 组件并编译成 JavaScript。这听起来可能效率低下，但 Vue 编译器足够聪明，可以将静态和动态部分分开，从而最大限度地减少激活成本和有效负载大小。

对于初始的页面加载，静态部分会自动从 JavaScript 有效负载中删除，并在激活期间跳过。

路由

基于文件的路由

VitePress 使用基于文件的路由，这意味着生成的 HTML 页面是从源 Markdown 文件的目录结构映射而来的。例如，给定以下目录结构：

.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md

生成的 HTML 页面会是这样：

index.md                  -->  /index.html (可以通过 / 访问)
prologue.md               -->  /prologue.html
guide/index.md            -->  /guide/index.html (可以通过 /guide/ 访问)
guide/getting-started.md  -->  /guide/getting-started.html

生成的 HTML 可以托管在任何支持静态文件的 Web 服务器上。

VitePress 项目的文件结构中有两个重要的概念：项目根目录 (project root) 和源目录 (source directory)。

项目根目录

项目根目录是 VitePress 将尝试寻找 .vitepress 特殊目录的地方。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的预留位置。

当从命令行运行 vitepress dev 或 vitepress build 时，VitePress 将使用当前工作目录作为项目根目录。要将子目录指定为根目录，需要将相对路径传递给命令。例如，如果 VitePress 项目位于 ./docs，应该运行 vitepress dev docs：

.
├─ docs                    # 项目根目录
│  ├─ .vitepress           # 配置目录
│  ├─ getting-started.md
│  └─ index.md
└─ ...

命令行启动

vitepress dev docs

这将导致以下源代码到 HTML 的映射：

docs/index.md            -->  /index.html (可以通过 / 访问)
docs/getting-started.md  -->  /getting-started.html

源目录

源目录是 Markdown 源文件所在的位置。默认情况下，它与项目根目录相同。但是，可以通过 srcDir 配置选项对其进行配置。

srcDir 选项是相对于项目根目录解析的。例如，对于 srcDir: 'src'，文件结构将如下所示：

示例 srcDir

export default {
  srcDir: './src'
}

结构目录

.                          # 项目根目录
├─ .vitepress              # 配置目录
└─ src                     # 源目录
   ├─ getting-started.md
   └─ index.md

生成的源代码到 HTML 的映射：

src/index.md            -->  /index.html (可以通过 / 访问)
src/getting-started.md  -->  /getting-started.html

链接页面

在页面之间链接时，可以使用绝对路径和相对路径。请注意，虽然 .md 和 .html 扩展名都可以使用，但最佳做法是省略文件扩展名，以便 VitePress 可以根据配置生成最终的 URL。

<!-- Do -->
[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)

<!-- Don't -->
[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)

在资源处理中了解有关链接到资源（例如图像）的更多信息。

链接非VitePress页面

如果想链接到站点中不是由 VitePress 生成的页面，需要使用完整的 URL（在新选项卡中打开）或明确指定 target：

输入

[Link to pure.html](/pure.html){target="_self"}

输出

Link to pure.html

注意：

在 Markdown 链接中，base 会自动添加到 URL 前面。这意味着，如果想链接到 base 之外的页面，则链接中需要类似 ../../pure.html 的内容（由浏览器相对于当前页面解析）。

或者，可以直接使用锚标记语法：

<a href="/pure.html" target="_self">Link to pure.html</a>

生成简洁的URL

需要服务器支持

要使 VitePress 提供简洁 URL，需要服务器端支持。

默认情况下，VitePress 将入站链接解析为以 .html 结尾的 URL。但是，一些用户可能更喜欢没有 .html 扩展名的“简洁 URL”——例如，example.com/path 而不是 example.com/path.html。

某些服务器或托管平台 (例如 Netlify、Vercel 或 GitHub Pages) 提供将 /foo 之类的 URL 映射到 /foo.html (如果存在) 的功能，而无需重定向：

Netlify 和 GitHub Pages 是默认支持的。
Vercel 需要在 vercel.json 中启用 cleanUrls 选项。

如果可以使用此功能，还可以启用 VitePress 自己的 cleanUrls 配置选项，以便：

页面之间的入站链接是在没有 .html 扩展名的情况下生成的。
如果当前路径以 .html 结尾，路由器将执行客户端重定向到无扩展路径。

但是，如果无法为服务器配置此类支持，则必须手动采用以下目录结构：

.
├─ getting-started
│  └─ index.md
├─ installation
│  └─ index.md
└─ index.md

下面以常用的nginx和apache服务端配置举例

Nginx配置静态文件服务

编辑你的Nginx配置文件（通常位于/etc/nginx/sites-available/目录下），添加如下配置：

server {
    listen 80; # 或者你选择的端口号
    server_name yourdomain.com; # 你的域名或IP地址
    location / {
        root /path/to/my-vitepress-site/.vitepress/dist; # VitePress构建后的输出目录路径
        try_files $uri $uri/ /index.html; # 处理单页应用路由问题
    }
}

确保重新加载Nginx配置：

sudo nginx -s reload

Apache配置静态文件服务

在Apache的配置文件中

（例如/etc/apache2/sites-available/yourdomain.com.conf），添加如下配置：

<VirtualHost *:80>
    ServerName yourdomain.com # 你的域名或IP地址
    DocumentRoot /path/to/my-vitepress-site/.vitepress/dist # VitePress构建后的输出目录路径
    <Directory /path/to/my-vitepress-site/.vitepress/dist>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Require all granted # 或者使用其他适当的访问控制策略，例如Require ip 192.168.1.1等。
    </Directory>
</VirtualHost>

然后，重新启动Apache服务：

sudo systemctl restart apache2 # 对于Debian/Ubuntu系统。对于其他系统，命令可能有所不同。例如，在CentOS上，可能是 `sudo systemctl restart httpd`。

常见报错问题

1.如果你遇到的问题是“404 Not Found”错误，这通常是因为请求的URL没有被正确映射到对应的静态文件。检查以下几点：

确保Nginx或Apache的配置正确指向了VitePress的输出目录。

如上所示的root或DocumentRoot指令。

确保使用了正确的URL重写规则。

对于Nginx，是 try_files $uri $uri/ /index.html;

对于Apache，通常是使用mod_rewrite模块来实现。例如，在.htaccess文件中添加：

RewriteEngine On
 
# 示例1: 将/old-page重写为/new-page
RewriteRule ^old-page/?$ /new-page [R=301,L]
 
# 示例2: 将/category/old-product重写为/category/new-product
RewriteRule ^category/old-product/?$ /category/new-product [R=301,L]
 
# 示例3: 使用正则表达式匹配并重写URL
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^blog/([0-9]+)/?$ /blog/post.php?id=$1 [L]

以上是nginx和apache的文件配置

2.报错信息：“The requested URL /example was not found on this server.”

解释：

这个错误通常表示Apache服务器无法找到请求的URL对应的文件或目录。这可能是因为：

1.URL路径错误。

2.Apache配置文件（如.htaccess）中的重写规则错误。

3.mod_rewrite模块未启用。

4.文件或目录确实不存在。

解决方法：

1.检查URL路径：确保URL正确无误，并且服务器上有对应的文件或目录。

2.检查.htaccess文件：确保.htaccess中的重写规则正确无误，并且适用于你的需求。例如，确认目标文件或目录路径正确。

3.启用mod_rewrite：在Apache的配置文件中（如httpd.conf或apache2.conf），确保有如下行：

LoadModule rewrite_module modules/mod_rewrite.so

并确保重启Apache服务。

4.检查文件存在性：使用文件浏览器或命令行工具（如ls命令）检查目标文件或目录是否真的存在于服务器上。

5.查看Apache错误日志：查看Apache的错误日志文件（如error_log），可能会提供更多关于问题的详细信息。

路由重写

可以自定义源目录结构和生成页面之间的映射。当有一个复杂的项目结构时，它很有用。例如，假设有一个包含多个包的 monorepo，并且希望将文档与源文件一起放置，如下所示：

.
├─ packages
│  ├─ pkg-a
│  │  └─ src
│  │      ├─ pkg-a-code.ts
│  │      └─ pkg-a-docs.md
│  └─ pkg-b
│     └─ src
│         ├─ pkg-b-code.ts
│         └─ pkg-b-docs.md

希望像这样生成 VitePress 页面：

packages/pkg-a/src/pkg-a-docs.md  -->  /pkg-a/index.html
packages/pkg-b/src/pkg-b-docs.md  -->  /pkg-b/index.html

可以通过像这样配置 rewrites 选项来实现此目的：

// .vitepress/config.js
export default {
  rewrites: {
    'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
    'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md'
  }
}

rewrites 选项还支持动态路由参数。在上面的示例中，如果有很多包，则列出所有路径会很冗长。鉴于它们都具有相同的文件结构，可以像这样简化配置：

export default {
  rewrites: {
    'packages/:pkg/src/(.*)': ':pkg/index.md'
  }
}

重写路径是使用 path-to-regexp 包编译的——请参阅其文档以获取更多语法。

开启重写功能时使用相对链接

启用重写后，相对链接应基于重写的路径。例如，为了创建从 packages/pkg-a/src/pkg-a-code.md 到 packages/pkg-b/src/pkg-b-code.md 的相对链接，应该使用：

[Link to PKG B](../pkg-b/pkg-b-code)

动态路由

可以使用单个 Markdown 文件和动态数据生成许多页面。例如，可以创建一个 packages/[pkg].md 文件，为项目中的每个包生成相应的页面。这里，[pkg] 段是一个路由参数，用于区分每个页面。

路径加载文件

由于 VitePress 是静态站点生成器，因此必须在构建时确定可能的页面路径。因此，动态路由页面必须伴随路径加载文件。对于 packages/[pkg].md，我们需要 packages/[pkg].paths.js (也支持 .ts)：

.
└─ packages
   ├─ [pkg].md         # 路由模板
   └─ [pkg].paths.js   # 路由路径加载器

路径加载器应该提供一个带有 paths 方法的对象作为其默认导出。paths 方法应返回具有 params 属性的对象数组。这些对象中的每一个都将生成一个相应的页面。

给定以下 paths 数组：

// packages/[pkg].paths.js
export default {
  paths() {
    return [
      { params: { pkg: 'foo' }},
      { params: { pkg: 'bar' }}
    ]
  }
}

生成的 HTML 页面将会是：

.
└─ packages
   ├─ foo.html
   └─ bar.html

多参数

动态路由可以包含多个参数：

文件结构

.
└─ packages
   ├─ [pkg]-[version].md
   └─ [pkg]-[version].paths.js

路径加载器

export default {
  paths: () => [
    { params: { pkg: 'foo', version: '1.0.0' }},
    { params: { pkg: 'foo', version: '2.0.0' }},
    { params: { pkg: 'bar', version: '1.0.0' }},
    { params: { pkg: 'bar', version: '2.0.0' }}
  ]
}

输出

.
└─ packages
   ├─ foo-1.0.0.html
   ├─ foo-2.0.0.html
   ├─ bar-1.0.0.html
   └─ bar-2.0.0.html

动态生成路径

路径加载器模块在 Node.js 中运行，并且仅在构建期间执行。可以使用本地或远程的任何数据动态生成路径数组。

从本地文件生成路径：

import fs from 'fs'

export default {
  paths() {
    return fs
      .readdirSync('packages')
      .map((pkg) => {
        return { params: { pkg }}
      })
  }
}

从远程数据生成路径：

export default {
  async paths() {
    const pkgs = await (await fetch('https://my-api.com/packages')).json()

    return pkgs.map((pkg) => {
      return {
        params: {
          pkg: pkg.name,
          version: pkg.version
        }
      }
    })
  }
}

访问页面参数

可以使用参数将附加数据传递到每个页面。Markdown 路由文件可以通过 $params 全局属性访问 Vue 表达式中的当前页面参数：

- package name: {
  { $params.pkg }}
- version: {
  { $params.version }}

还可以通过 useData 运行时 API 访问当前页面的参数。这在 Markdown 文件和 Vue 组件中都可用：

<script setup>
import { useData } from 'vitepress'

// params 是一个 Vue ref
const { params } = useData()

console.log(params.value)
</script>

渲染原始内容

传递给页面的参数将在客户端 JavaScript payload 中序列化，因此应该避免在参数中传递大量数据，例如从远程 CMS 获取的原始 Markdown 或 HTML 内容。

相反，可以使用每个路径对象上的 content 属性将此类内容传递到每个页面：

export default {
  async paths() {
    const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

    return posts.map((post) => {
      return {
        params: { id: post.id },
        content: post.content // 原始 Markdown 或 HTML
      }
    })
  }
}

然后，使用以下特殊语法将内容呈现为 Markdown 文件本身的一部分：

<!-- @content -->

部署

部署VitePress站点

以下指南基于一些前提：

VitePress 站点位于项目的 docs 目录中。

你使用的是默认的生成输出目录（.vitepress/dist）。

VitePress 作为本地依赖项安装在项目中，并且你已在 package.json 中设置以下脚本：

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

本地构建与测试

1.可以运行以下命令来构建文档：

npm run docs:build

2.构建文档后，通过运行以下命令可以在本地预览它：

npm run docs:preview

preview 命令将启动一个本地静态 Web 服务 http://localhost:4173，该服务以 .vitepress/dist 作为源文件。这是检查生产版本在本地环境中是否正常的一种简单方法。

3.可以通过传递 --port 作为参数来配置服务器的端口。

{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}

现在 docs:preview 方法将会在 http://localhost:8080 启动服务。

设定public根目录

默认情况下，我们假设站点将部署在域名 (/) 的根路径上。如果站点在子路径中提供服务，例如 https://mywebsite.com/blog/，则需要在 VitePress 配置中将 base 选项设置为 '/blog/'。

例：如果你使用的是 Github（或 GitLab）页面并部署到 user.github.io/repo/，请将 base设置为 /repo/。

HTTP缓存标头

如果可以控制生产服务器上的 HTTP 标头，则可以配置 cache-control 标头以在重复访问时获得更好的性能。

生产版本对静态资源 (JavaScript、CSS 和其他非 public 目录中的导入资源) 使用哈希文件名。如果你使用浏览器开发工具的网络选项卡查看生产预览，你将看到类似 app.4f283b18.js 的文件。

此哈希 4f283b18 是从此文件的内容生成的。相同的哈希 URL 保证提供相同的文件内容——如果内容更改，URL 也会更改。这意味着你可以安全地为这些文件使用最强的缓存标头。所有此类文件都将放置在输出目录的 assets/ 中，因此你可以为它们配置以下标头：

Cache-Control: max-age=31536000,immutable

Netlify示例 _headers文件

/assets/*
  cache-control: max-age=31536000
  cache-control: immutable

vercel配置示例 vercel.json

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

平台部署指南

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

使用仪表板创建新项目并更改这些设置：

构建命令： npm run docs:build
输出目录： docs/.vitepress/dist
node 版本： 18 (或更高版本)

WARNING

不要为 HTML 代码启用 Auto Minify 等选项。它将从输出中删除对 Vue 有意义的注释。如果被删除，你可能会看到激活不匹配错误。

GitHub Pages

1.在项目的 .github/workflows 目录中创建一个名为 deploy.yml 的文件，其中包含这样的内容：

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
#
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
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@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消注释
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun 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
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

确保 VitePress 中的 base 选项配置正确。有关更多详细信息，请参阅设置根路径。

2.在存储库设置中的“Pages”菜单项下，选择“Build and deployment > Source > GitHub Actions”。

3.将更改推送到 main 分支并等待 GitHub Action 工作流完成。你应该看到站点部署到 https://<username>.github.io/[repository]/ 或 https://<custom-domain>/，这取决于你的设置。你的站点将在每次推送到 main 分支时自动部署。

GitLab Pages

1.如果你想部署到 https://<username> .gitlab.io/<repository> /，将 VitePress 配置中的 outDir 设置为 ../public。将 base 选项配置为 '/<repository>/'。

2.在项目的根目录中创建一个名为 .gitlab-ci.yml 的文件，其中包含以下内容。每当你更改内容时，这都会构建和部署你的站点：

image: node:18
pages:
  cache:
    paths:
      - node_modules/
  script:
    # - apk add git # 如果你使用的是像 alpine 这样的小型 docker 镜像，并且启用了 lastUpdated，请取消注释
    - npm install
    - npm run docs:build
  artifacts:
    paths:
      - public
  only:
    - main

Azure 静态 web 应用

参考官方文档。

在配置文件中设置这些值 (并删除不需要的值，如 api_location)：

app_location: /

output_location: docs/.vitepress/dist

app_build_command: npm run docs:build

Firebase

1.在项目的根目录下创建 firebase.json 和 .firebaserc：

firebase.json:

{
  "hosting": {
    "public": "docs/.vitepress/dist",
    "ignore": []
  }
}

.firebaserc:

{
  "projects": {
    "default": "<YOUR_FIREBASE_ID>"
  }
}

2.运行 npm run docs:build 后，运行此命令进行部署：

firebase deploy

Surge

运行 npm run docs:build 后，运行此命令进行部署：

npx surge docs/.vitepress/dist

Heroku

参考 heroku-buildpack-static 中给出的文档和指南。

使用以下内容在项目的根目录中创建一个名为 static.json 的文件：

{
  "root": "docs/.vitepress/dist"
}

Edgio

请参阅创建并部署 VitePress 应用程序到 Edgio。

Kinsta 静态站点托管

你可以按照这些说明在 Kinsta 上部署 VitePress 站点。

Stormkit

你可以按照这些说明将你的 VitePress 项目部署到 Stormkit。

Nginx

下面是一个 Nginx 服务器块配置示例。此配置包括对基于文本的常见资源的 gzip 压缩、使用适当缓存头为 VitePress 站点静态文件提供服务的规则以及处理 cleanUrls: true 的方法。

server {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    listen 80;
    server_name _;
    index index.html;

    location / {
        # content location
        root /app;

        # exact matches -> reverse clean urls -> folders -> not found
        try_files $uri $uri.html $uri/ =404;

        # non existent pages
        error_page 404 /404.html;

        # a folder without index.html raises 403 in this setup
        error_page 403 /404.html;

        # adjust caching headers
        # files in the assets folder have hashes filenames
        location ~* ^/assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}

本配置默认已构建的 VitePress 站点位于服务器上的 /app 目录中。如果站点文件位于其他位置，请相应调整 root 指令。

不要默认为 index.html

try_files 解析不能像其他 Vue 应用那样默认为 index.html。这会导致页面状态处于无效。

更多信息请参见 nginx 官方文档、这些 GitHub Issue #2837、#3235以及 Mehdi Merah 发表的博客。

Mehdi博客内容

解决方案配置

仅供参考

server {
    index index.html;
    rewrite ^(.+)/$ $1 permanent;

    if ($request_uri ~ ^/(.*)index\.html(\?|$)) {
        return 301 /$1;
    }

    if ($request_uri ~ ^/(.*)\.html(\?|$)) {
        return 301 /$1;
    }

    location / {
        error_page 404 /404.html;
        try_files $uri $uri.html $uri/ =404;
    }
}

server {
    index index.html;
    # and other things…

    # Remove the trailing slash (permanent 301 redirect). 
    rewrite ^(.+)/$ $1 permanent;

    # Remove the trailing `index.html`. 
    if ($request_uri ~ ^/(.*)index\.html(\?|$)) {
        return 301 /$1;
    }

    # Remove the trailing `.html`. 
    if ($request_uri ~ ^/(.*)\.html(\?|$)) {
        return 301 /$1;