前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载VitePress 是一个基于 Vite 与 Vue 的静态站点生成器它把 Markdown 文档编译为纯静态的 HTML、CSS 与 JS 产物天然适合部署到各类静态托管平台。本文以仓库内 docs/fa/guide/deploy.md 为骨架系统讲解 VitePress 站点的本地构建与预览、公共基础路径base配置、HTTP 缓存头优化以及 Netlify、Vercel、GitHub Pages、GitLab Pages、Firebase、Nginx 等主流平台的完整上线流程并结合仓库源码CLI 入口、预览服务器、站点配置解析说明底层机制帮助你一次性掌握从npm run docs:build到生产环境稳定运行的完整链路。部署前的共同假设官方部署指南基于以下三个约定请先确认你的项目满足这些前提站点源码位于项目的docs目录下即 Markdown 源文件都放在docs中使用默认的构建输出目录.vitepress/distVitePress 以本地依赖安装并在 package.json 中配置了如下脚本{ scripts: { docs:build: vitepress build docs, docs:preview: vitepress preview docs } }其中docs:build负责把docs目录编译为静态产物docs:preview负责在本地以生产模式预览构建结果。命令解析逻辑位于 src/node/cli.tsCLI 通过minimist解析参数识别build、serve别名preview、dev、init等子命令并把build交给构建流程、把serve/preview交给 src/node/serve/serve.ts 的serve()函数处理。本地构建与测试1. 构建文档$ npm run docs:build该命令会执行vitepress build docs将 Markdown 渲染为静态 HTML并把 JS/CSS 等资源打包到docs/.vitepress/distoutDir的默认解析见 src/node/config.ts 中的resolve(root, dist)。2. 本地预览构建产物$ npm run docs:previewpreview命令会启动一个本地静态服务器将输出目录.vitepress/dist通过http://localhost:4173提供服务。部署前先用它检查页面渲染是否符合预期可以有效避免把问题带到生产环境。从源码看默认端口4173定义在 src/node/serve/serve.tsconst port options.port ?? 4173。预览服务器基于polkasirv实现对assets/目录下的指纹资源设置maxAge: 31536000, immutable对非资源文件强制cache-control: no-cache促使浏览器每次向服务器校验避免未带哈希的文件被长期缓存请求不存在的路径时回退到构建产物中的404.html若配置了非根base还会把/请求 302 重定向到/{base}/。3. 自定义端口可以通过--port参数指定端口{ scripts: { docs:preview: vitepress preview docs --port 8080 } }此时docs:preview会在http://localhost:8080启动服务器。--port参数最终会传入serve()的options.port见 src/node/serve/serve.ts 的ServeOptions接口。设置公共基础路径base默认情况下VitePress 假设站点部署在域名根路径/下。如果你的站点需要部署在子路径例如https://mywebsite.com/blog/就必须在 VitePress 配置中把base设置为/blog/。示例如果使用 GitHub Pages或 GitLab Pages并部署到user.github.io/repo/则应将base设为/repo/。base选项的语义在 src/node/siteConfig.ts 中有明确注释它表示站点部署的基础 URL通常以斜杠开头和结尾默认值为/。base会作用于页面链接、withBase生成的链接、public/目录文件以及hashmap.json等是子路径部署时最容易出错也最关键的一项配置。可迁移构建相对 base如果站点最终 URL 在构建时不可预知例如部署到 IPFS 网关、共享文件夹、或需要打进某个应用可以把base设为./export default { base: ./ }此时每个页面都会以自身位置为基准引用资源和其他页面客户端运行时会根据实际加载的 URL 恢复真实挂载点同一份构建产物可以不经重新构建地部署到任意子路径。isRelativeBase的实现见 src/shared/shared.tsbase ./预览服务器在遇到相对 base 时也会回退到根路径挂载见 src/node/serve/serve.ts。需要注意相对 base 下应保持cleanUrls关闭默认即关闭因为可迁移产物需要以.html结尾的链接且cleanUrls配合相对 base 构建时 src/node/config.ts 会给出警告。HTTP 缓存头优化生产构建会对静态资源JS、CSS 及其他不在public中的导入资源使用哈希文件名。用浏览器开发者工具的 Network 面板查看生产预览会看到类似app.4f283b18.js的文件。4f283b18这个哈希由文件内容生成内容不变则 URL 不变内容一变 URL 必变。因此可以放心地对这些文件使用最强缓存头。所有此类文件都会放在输出目录的assets/子目录下只需对该目录配置Cache-Control: max-age31536000,immutableNetlify 示例_headers文件/assets/* cache-control: max-age31536000 cache-control: immutable注意_headers文件应放在 public 目录本例为docs/public/_headers中构建时它才会被原样复制到输出目录。Vercel 示例配置vercel.json{ headers: [ { source: /assets/(.*), headers: [ { key: Cache-Control, value: max-age31536000, immutable } ] } ] }注意vercel.json应放在仓库根目录。值得补充的是VitePress 内置的预览服务器已经实现了与上述一致的缓存策略——src/node/serve/serve.ts 对assets/下的指纹资源直接返回maxAge: 31536000, immutable对非资源文件则返回no-cache。这说明指纹资源长缓存、非指纹资源强制校验是官方推荐的标准缓存模型你可以照此在自己的生产服务器上复刻。平台部署指南Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render新建项目后在对应平台的控制台配置以下参数构建命令Build Commandnpm run docs:build输出目录Output Directorydocs/.vitepress/distNode 版本20或更高::: warning 警告 不要启用Auto MinifyHTML 自动压缩之类的选项。这类工具会移除输出 HTML 中对 Vue 有意义的注释一旦被移除运行时可能出现水合hydration不匹配错误。 :::GitHub Pages在项目的.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/checkoutv5 with: fetch-depth: 0 # 未启用 lastUpdated 时不需要 # - uses: pnpm/action-setupv4 # 使用 pnpm 时取消注释 # with: # version: 9 # 已在 package.json 中设置 packageManager 时不需要 # - 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::: warning 警告 请确保 VitePress 的base选项已正确配置详见上文设置公共基础路径一节。 :::在仓库 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。在项目根目录创建.gitlab-ci.yml内容如下。它会在内容发生变化时自动构建并发布站点image: node:24 pages: cache: paths: - node_modules/ script: # - apk add git # 使用 alpine 等小型镜像且启用了 lastUpdated 时取消注释 - npm install - npm run docs:build artifacts: paths: - public only: - main注意outDir之所以要改为../public是因为 GitLab Pages 约定把public目录作为发布根目录outDir在 src/node/config.ts 中的默认值是项目根下的dist这里需要显式覆盖。Azure Static Web Apps遵循 Azure Static Web Apps 官方构建配置文档 的操作步骤。在配置文件中设置以下值不需要的项如api_location直接删除app_location/output_locationdocs/.vitepress/distapp_build_commandnpm run docs:buildCloudRay可以按照 CloudRay 官方部署 VitePress 的指引 将 VitePress 项目发布到 CloudRay。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中的文档与指南。在项目根目录创建static.json{ root: docs/.vitepress/dist }Hostinger可以按照 Hostinger 的 Node.js 网站部署说明 将 VitePress 项目发布到 Hostinger。配置构建设置时选择VitePress作为框架并把根目录root directory调整为./docs。Kinsta可以按照 Kinsta 的 VitePress 静态站点示例文档 将 VitePress 网站发布到 Kinsta。Stormkit可以按照 Stormkit 的 VitePress 部署说明 将 VitePress 项目发布到 Stormkit。Surge先执行npm run docs:build完成构建再运行npx surge docs/.vitepress/dist将docs/.vitepress/dist目录发布到 Surge。Nginx下面是一份 Nginx server 块配置示例。它包含针对常见文本类资源的 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 反向 - 目录 - 404 try_files $uri $uri.html $uri/ 404; # 不存在的页面 error_page 404 /404.html; # 无 index.html 的目录在此配置下会返回 403 error_page 403 /404.html; # 调整缓存头 # assets 目录中的文件均带哈希文件名 location ~* ^/assets/ { expires 1y; add_header Cache-Control public, immutable; } } }该配置假设构建产物位于服务器的/app目录如果你的站点文件在别处请用相应的root指令调整路径。::: warning 警告try_files的配置不要像其他 Vue 应用那样默认回退到index.html否则会导致页面状态路由失效。 :::如需更多信息可查阅 nginx 官方文档、相关讨论如 vuejs/vitepress 的 discussion #2837、issue #3235以及 Mehdi Merah 关于 VitePress cleanUrls 与 Nginx 环境的博客文章。部署排查要点样式/资源 404绝大多数是base未配置或配置错误。子路径部署务必确认base与平台 URL 前缀一致如 GitHub Pages 的/repo/相对 base./场景请保持cleanUrls关闭。水合错误检查平台是否启用了 HTML Auto Minify它会删除 Vue 需要的注释参见上文通用平台配置中的警告。lastUpdated不生效GitHub Actions 的 checkout 步骤需要fetch-depth: 0工作流中已带注释说明使用 alpine 等小型 Docker 镜像的 GitLab CI 则需要apk add git.gitlab-ci.yml中已预留注释。缓存不更新确认assets/使用了长缓存max-age31536000, immutable而 HTML 等非指纹文件未被强缓存这与 src/node/serve/serve.ts 内置预览服务器的行为保持一致。Node 版本各平台示例要求 Node20或更高GitHub Actions 工作流与 GitLab CI 镜像分别使用24请保证平台 Node 版本满足要求。至此你已经掌握了 VitePress 站点从本地构建、路径配置、缓存优化到多平台部署的完整方案。以 docs/fa/guide/deploy.md 为对照结合 src/node/cli.ts、src/node/serve/serve.ts 与 src/node/siteConfig.ts 等源码阅读可以进一步深入理解每一步背后的实现细节。赞分享前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载相关推荐LivePortrait全平台部署指南从环境配置到动画生成的完整路径LivePortrait全平台部署指南从环境配置到动画生成的完整路径 LivePortrait作为一款高效的人像动画工具支持将静态肖像转化为生动的动态效果人工智能计算机视觉媒体生成数字人DGIOT平台部署完全指南从CentOS一键安装到生产环境配置DGIOT平台部署完全指南从CentOS一键安装到生产环境配置 DGIOT作为国内首个轻量级开源工业物联网平台为企业提供了从设备接入到数据分析的完整解决方案物联网后端消息队列Cube Sandbox 本地构建部署全指南从源码打包到单机一键部署Cube Sandbox 本地构建部署全指南从源码打包到单机一键部署 Cube Sandbox 是面向 AI Agent 的即时、高并发、安全且轻量的沙箱平台Agent 沙箱虚拟化云原生人工智能后端容器运行时上一篇Skia文本字距微调终极指南像素级对齐与视觉平衡的艺术下一篇如何利用Jigsaw-Payment构建高并发支付服务性能优化实践分享创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考