前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载VitePress 是 Vite 与 Vue 驱动的静态站点生成器其部署流程本质上是一次构建 托管静态产物的过程。本文围绕 VitePress 官方部署文档docs/es/guide/deploy.md展开系统讲解本地构建预览、公共路径base配置、缓存头优化以及 Netlify、Vercel、Cloudflare Pages、GitHub Pages、GitLab Pages、Firebase、Nginx 等十余个平台的完整部署方案。读完本文你将掌握从package.json脚本配置到生产环境上线的一整套可复现操作并能根据托管平台的差异正确设置base、输出目录与缓存策略。部署前的统一假设官方部署指南基于以下三个前提理解它们有助于后续所有配置对齐站点源码位于项目的docs目录下使用默认构建输出目录.vitepress/dist源码中 outDir 的默认值 即为./.vitepress/distVitePress 作为本地依赖安装并在package.json中配置了如下脚本{ scripts: { docs:build: vitepress build docs, docs:preview: vitepress preview docs } }当前仓库自身的根 package.json 也遵循同样的组织方式docs:build与docs:preview通过 pnpm workspace 转调docs包的对应脚本验证了这一约定在真实项目中的落地形态。本地构建与预览构建命令在项目根目录执行$ npm run docs:build该命令会调用 VitePress 的build子命令。从 src/node/cli.ts 的入口逻辑可以看到CLI 通过minimist解析参数将docs识别为root后交给build(root, argv)处理最终把 Markdown 内容渲染为静态 HTML 输出到.vitepress/dist。本地预览构建完成后执行$ npm run docs:previewpreview与serve等价会启动一个本地静态 Web 服务器将.vitepress/dist目录在http://localhost:4173上提供服务用于在上线前检查一切是否正常。在 src/node/serve/serve.ts 中可以看到默认端口正是options.port ?? 4173服务器基于polkasirv构建并默认对带 hash 的静态资源设置了maxAge: 31536000与immutable缓存头这一点与下文HTTP 缓存头章节的设计完全对应。自定义预览端口通过--port参数可以指定端口{ scripts: { docs:preview: vitepress preview docs --port 8080 } }此时预览服务器会运行在http://localhost:8080。CLI 会将--port 8080解析为argv.port并透传给serve()最终由app.listen(port)生效。配置公共 base 路径默认情况下VitePress 假设站点部署在域名根路径/。如果站点要从子路径提供服务例如https://meusite.com/blog/则需要将配置中的base设置为/blog/。// .vitepress/config.ts export default { base: /blog/ }典型示例使用 GitHub Pages或 GitLab Pages部署到user.github.io/repo/时将base设置为/repo/。base 的约束与校验逻辑从源码层面看base的解析并非简单的字符串拼接在 src/node/config.ts 的normalizeSiteBase中base会被补全末尾斜杠并强制要求以/开头若以.开头但又不是恰好等于./会直接抛出错误——相对路径 base 只允许精确的./src/node/siteConfig.ts 中的类型注释明确base是站点部署的基准 URL通常以斜杠开头和结尾默认值为/在 docs/es/reference/site-config.md#base 中还特别说明base会自动附加到其他选项中以/开头的所有 URL 上因此只需配置一次。可迁移构建使用相对 base./除常规的子路径部署外当前版本还支持一种可迁移构建模式当站点最终 URL 在构建时不可知例如 IPFS 网关、共享文件夹、打包进应用的文档等场景时可将base设置为./export default { base: ./ }在这种模式下每个页面都会以自身位置为基准相对引用资源和其它页面客户端运行时在页面加载时会自动还原真实的挂载点同一份构建产物可以在任意子路径下工作甚至同时挂载多处路由、搜索与预取功能保持完整。直接通过file://打开生成的 HTML 也能作为带样式的可导航静态站点使用浏览器会拦截file://下的 JS 模块因此不会有水合搜索等交互功能保持未激活但所有预渲染内容和链接都可用。需要留意以下几点均可在 docs/en/guide/deploy.md#relocatable-builds-relative-base 中查阅保持cleanUrls关闭默认即如此可移植输出需要以.html结尾的链接因为没有服务器来改写美化 URL404.html仅在根深度生成任意深度路径的 fallback 页面可能不带样式head中的条目原样输出应避免使用/favicon.ico这类根绝对路径改用绝对 URL 或transformHeadMarkdown 中的原生 HTMLa标签会保持原样href站内绝对链接请使用 Markdown 链接语法开发服务器始终以/提供服务相对行为只作用于生产构建。源码层面src/shared/shared.ts 定义了RELATIVE_BASE_SENTINEL哨兵值与isRelativeBase(base)判断仅当base ./为真构建与预览流程据此切换链接生成方式同时 src/node/config.ts 会在base为相对值且开启cleanUrls时输出警告提示该组合需要服务端重写支持。HTTP 缓存头优化如果对生产服务器的 HTTP 响应头有控制权可以配置cache-control头来显著提升重复访问性能。生产构建会对静态资源JavaScript、CSS 及其它不在public目录中的导入资源使用带 hash 的文件名。用浏览器开发者工具的 Network 面板检查生产预览你会看到类似app.4f283b18.js的文件。这个4f283b18hash 由文件内容生成相同的 hash URL 保证提供相同的文件内容——内容一旦变化URL 也随之变化。这意味着可以为这些文件放心使用最强的缓存头。所有此类文件都会输出到assets/目录下因此可以配置如下响应头Cache-Control: max-age31536000,immutableNetlify 的_headers示例/assets/* cache-control: max-age31536000 cache-control: immutable注意_headers文件应放在 public 目录 中——本例即docs/public/_headers——它会被原样复制到输出目录。public 目录中的静态资源会按原文件名拷入构建输出根目录参见 docs/es/guide/asset-handling.md 中关于 public 目录的说明因此该文件最终会随构建产物一起发布。Vercel 的vercel.json示例{ headers: [ { source: /assets/(.*), headers: [ { key: Cache-Control, value: max-age31536000, immutable } ] } ] }注意vercel.json需要放在仓库根目录。与文档建议一致src/node/serve/serve.ts 中的本地预览服务器对assets/下的文件同样启用了maxAge: 31536000与immutable而对非 hash 页面文件设置no-cache强制服务器校验——这是hash 资源可长期缓存、页面文件需及时更新这一策略在实现层的直接体现。各平台部署指南通用平台Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render新建项目后在对应平台控制台完成以下设置构建命令Build Commandnpm run docs:build输出目录Output Directorydocs/.vitepress/distNode 版本20或更高⚠️ 警告 不要启用 HTML 代码的Auto Minify之类的选项。它会移除输出中带有 Vue 语义的注释一旦被移除可能出现水合不匹配hydration mismatch错误。GitHub Pages在项目.github/workflows目录下创建deploy.yml文件内容如下# 用于构建并部署 VitePress 站点到 GitHub Pages 的示例工作流 name: Deploy VitePress site to Pages on: # 针对 main 分支的推送触发。如果默认分支是 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/checkoutv5 with: fetch-depth: 0 # 未启用 lastUpdated 时不需要 # - uses: pnpm/action-setupv4 # 使用 pnpm 时取消注释 # with: # version: 9 # - uses: oven-sh/setup-bunv1 # 使用 Bun 时取消注释 - name: Setup Node uses: actions/setup-nodev6 with: node-version: 24 cache: npm # 或 pnpm / yarn - name: Cache VitePress uses: actions/cachev4 with: path: docs/.vitepress/cache key: ${{ runner.os }}-vitepress-${{ hashFiles(docs/**, package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb) }} restore-keys: | ${{ runner.os }}-vitepress- - name: Setup Pages uses: actions/configure-pagesv4 - 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-artifactv3 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-pagesv4⚠️ 警告 请确保 VitePress 中的base选项配置正确详见上文 配置公共 base 路径 一节。缓存目录docs/.vitepress/cache与cacheDir配置相关参见 docs/es/reference/site-config.md 中关于构建选项的说明。在仓库 Settings 的 Pages 菜单项下将 Build and deployment Source 选择为 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/。如果使用自定义域名、用户或组 Pages或已在 GitLab 中启用 Use unique domain 设置则无需base。outDir的具体语义可参考 docs/es/reference/site-config.md#outdir。在项目根目录创建.gitlab-ci.yml内容如下。它会在内容发生变化时自动构建并部署站点image: node:24 pages: cache: paths: - node_modules/ script: # - apk add git # 使用 alpine 等小型 docker 镜像且启用 lastUpdated 时取消注释 - npm install - npm run docs:build artifacts: paths: - public only: - mainAzureAzure Static Web Apps遵循 Azure Static Web Apps 官方构建配置文档的指引。在配置文件如staticwebapp.config.json中设置以下值不需要的项请移除例如api_locationapp_location/output_locationdocs/.vitepress/distapp_build_commandnpm run docs:buildCloudRay可以在 CloudRay 平台部署 VitePress 项目。构建命令使用npm run docs:build输出目录为docs/.vitepress/distNode 版本选择 20 及以上按平台指引完成项目创建与发布即可。Firebase在项目根目录创建firebase.json和.firebasercfirebase.json{ hosting: { public: docs/.vitepress/dist, ignore: [] } }.firebaserc{ projects: { default: YOUR_FIREBASE_ID } }执行npm run docs:build后运行firebase deployHeroku按照heroku-buildpack-static提供的文档和指南完成 buildpack 配置。在项目根目录创建static.json{ root: docs/.vitepress/dist }Hostinger可以在 Hostinger 的 Web Apps 托管中部署 VitePress 项目在构建设置中选择 VitePress 作为框架并将根目录调整为./docs其余按平台提示操作。Kinsta可以在 Kinsta 静态站点托管中部署 VitePress 站点按照其官方 VitePress 静态站点示例文档配置即可。Stormkit可以在 Stormkit 上部署 VitePress 项目按其官方部署指引完成连接仓库与构建配置即可。Surge执行npm run docs:build后运行npx surge docs/.vitepress/distNginx以下是 Nginx 服务器块server block配置示例。该配置包含常用文本资源的 gzip 压缩、为 VitePress 静态文件设置合适的缓存响应头以及对cleanUrls: true的处理server { gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript; listen 80; server_name _; index index.html; location / { # 内容位置 root /app; # 精确匹配 - 反向 clean urls - 目录 - 未找到 try_files $uri $uri.html $uri/ 404; # 不存在的页面 error_page 404 /404.html; # 该配置下没有 index.html 的目录会返回 403 error_page 403 /404.html; # 调整缓存响应头 # assets 目录下的文件带有 hash 文件名 location ~* ^/assets/ { expires 1y; add_header Cache-Control public, immutable; } } }该配置假设构建产物位于服务器/app目录若站点文件位于其他位置请相应调整root指令。⚠️ 警告try_files的解析不应像其它 Vue 应用那样默认回退到index.html否则会导致无效的页面状态。其他平台的补充说明除了上文平台当前仓库的英文版部署文档docs/en/guide/deploy.md还收录了 Lizard 与 harvis 的部署方式Lizard 支持自动检测docs:build并将docs/.vitepress/dist在 80 端口提供服务harvis 同样可在构建后通过npx harvis docs/.vitepress/dist发布。具体命令与配置均以对应平台的官方指引为准。部署自检清单上线前建议逐项核对本地先验证依次运行npm run docs:build与npm run docs:preview确认http://localhost:4173上页面、路由与资源加载正常base 是否匹配托管路径部署到子路径时确认base已正确设置GitHub/GitLab Pages 尤其关键必要时使用./获得可迁移构建输出目录与构建命令各平台控制台/配置文件中的输出目录统一为docs/.vitepress/dist构建命令统一为npm run docs:buildNode 版本不低于 20缓存头策略对assets/下带 hash 的资源使用Cache-Control: max-age31536000, immutableNetlify 用_headersVercel 用vercel.jsonNginx 用location ~* ^/assets/规则关闭 HTML 压缩/自动 minify避免移除 Vue 水合所需的注释导致运行时错误Nginx 等自托管场景try_files不要回退index.html确保 404/403 正确映射到404.html。完成以上检查后即可在所选平台上正式发布站点。赞分享前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载相关推荐LivePortrait深度解析从静态肖像到动态动画的完整指南LivePortrait深度解析从静态肖像到动态动画的完整指南 技术价值定位与核心优势 LivePortrait 是一款革命性的AI驱动人像动画工具它将静态人工智能计算机视觉媒体生成数字人VitePress部署终极指南Netlify、Vercel和GitHub Pages全攻略VitePress部署终极指南Netlify、Vercel和GitHub Pages全攻略 想要将你的VitePress站点快速部署到生产环境吗本指南将为你前端文档al-folio 安装与部署完全指南从 Docker 本地开发到 GitHub Pages / Netlify 上线al folio 安装与部署完全指南从 Docker 本地开发到 GitHub Pages / Netlify 上线 本篇指南以 al folio 学术主题仓前端上一篇CANN通信算子开发API下一篇从源码学设计ankerl::unordered_dense的底层数据结构与实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考