部署您的 VitePress 网站
以下指南基于一些共同的假设
VitePress 网站位于您项目中的
docs
目录中。您使用的是默认的构建输出目录 (
.vitepress/dist
)。VitePress 作为本地依赖项安装在您的项目中,并且您已在
package.json
中设置了以下脚本json{ "scripts": { "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs" } }
本地构建和测试
运行此命令以构建文档
sh$ npm run docs:build
构建完成后,通过运行以下命令在本地预览它
sh$ npm run docs:preview
preview
命令将启动一个本地静态 Web 服务器,该服务器将在https://127.0.0.1:4173
上提供输出目录.vitepress/dist
。您可以使用它来确保在推送到生产环境之前一切正常。您可以通过传递
--port
作为参数来配置服务器的端口。json{ "scripts": { "docs:preview": "vitepress preview docs --port 8080" } }
现在,
docs:preview
方法将在https://127.0.0.1:8080
上启动服务器。
设置公共基本路径
默认情况下,我们假设网站将部署在域的根路径 (/
) 上。如果您的网站将在子路径上提供服务,例如 https://mywebsite.com/blog/
,那么您需要将 base
选项设置为 '/blog/'
在 VitePress 配置中。
示例:如果您使用的是 Github(或 GitLab)Pages 并部署到 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
注意:_headers
文件应放置在 public 目录 中 - 在我们的例子中,docs/public/_headers
- 这样它就会逐字复制到输出目录中。
示例 Vercel 配置在 vercel.json
中
{ "headers": [ { "source": "/assets/(.*)", "headers": [ { "key": "Cache-Control", "value": "max-age=31536000, immutable" } ] } ] }
注意:vercel.json
文件应放置在您的存储库的根目录中。
平台指南
Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render
设置一个新项目并使用您的仪表板更改这些设置
- 构建命令:
npm run docs:build
- 输出目录:
docs/.vitepress/dist
- 节点版本:
18
(或更高版本)
警告
不要为 HTML 代码启用诸如自动缩小之类的选项。它将从输出中删除对 Vue 有意义的注释。如果它们被删除,您可能会看到水合不匹配错误。
GitHub Pages
在您项目的
.github/workflows
目录中创建一个名为deploy.yml
的文件,其中包含以下内容yaml# Sample workflow for building and deploying a VitePress site to GitHub Pages # name: Deploy VitePress site to Pages on: # Runs on pushes targeting the `main` branch. Change this to `master` if you're # using the `master` branch as the default branch. push: branches: [main] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: contents: read pages: write id-token: write # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. concurrency: group: pages cancel-in-progress: false jobs: # Build job build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 # Not needed if lastUpdated is not enabled # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun - name: Setup Node uses: actions/setup-node@v4 with: node-version: 20 cache: npm # or pnpm / yarn - name: Setup Pages uses: actions/configure-pages@v4 - name: Install dependencies run: npm ci # or pnpm install / yarn install / bun install - name: Build with VitePress run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: docs/.vitepress/dist # Deployment job 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
选项配置正确。有关更多详细信息,请参阅 设置公共基本路径。在您的存储库设置中,在“Pages”菜单项下,在“构建和部署 > 源”中选择“GitHub Actions”。
将您的更改推送到
main
分支,并等待 GitHub Actions 工作流完成。您应该看到您的网站部署到https://<username>.github.io/[repository]/
或https://<custom-domain>/
,具体取决于您的设置。您的网站将在每次推送到main
分支时自动部署。
GitLab Pages
在 VitePress 配置中将
outDir
设置为../public
。如果您想部署到https://<username>.gitlab.io/<repository>/
,请将base
选项配置为'/<repository>/'
。在您项目的根目录中创建一个名为
.gitlab-ci.yml
的文件,其中包含以下内容。这将在您对内容进行更改时构建和部署您的网站yamlimage: node:18 pages: cache: paths: - node_modules/ script: # - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled - 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
在项目的根目录创建
firebase.json
和.firebaserc
文件firebase.json
:json{ "hosting": { "public": "docs/.vitepress/dist", "ignore": [] } }
.firebaserc
:json{ "projects": { "default": "<YOUR_FIREBASE_ID>" } }
运行
npm run docs:build
后,运行以下命令进行部署shfirebase deploy
Surge
运行
npm run docs:build
后,运行以下命令进行部署shnpx surge docs/.vitepress/dist
Heroku
请遵循
heroku-buildpack-static
中提供的文档和指南。在项目的根目录创建一个名为
static.json
的文件,内容如下json{ "root": "docs/.vitepress/dist" }
Edgio
请参考 将 VitePress 应用创建并部署到 Edgio。
Kinsta 静态网站托管
您可以按照以下 说明,将您的 Vitepress 网站部署到 Kinsta。
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 文档、这些问题 #2837、#3235 以及 Mehdi Merah 的这篇 博客文章 中找到。