☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
Vite 静态站点部署完全指南：从 vite build 到 GitHub Pages、Netlify、Vercel 与 Cloudflare 的完整落地方案
2026/9/5 19:25:02 网站建设 项目流程

Vite 静态站点部署完全指南：从 vite build 到 GitHub Pages、Netlify、Vercel 与 Cloudflare 的完整落地方案

【免费下载链接】viteNext generation frontend tooling. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite

本文基于 Vite 官方文档 静态部署指南 整理并深入扩充。文中覆盖 Vite 生产构建（vite build）、本地预览（vite preview）的完整流程与原理，并逐一给出 GitHub Pages、GitLab Pages、Netlify、Vercel、Cloudflare、Firebase、Surge、Azure Static Web Apps、Render 等主流平台的部署配置。读完本文，你可以独立完成一个 Vite 项目的生产构建、本地验证，并将其静态产物发布到几乎任何常见的静态托管平台。

前置约定：构建产物、npm 脚本与适用边界

官方部署指南基于以下三条共享假设，所有平台步骤都建立在这些默认值之上：

  • 使用默认构建输出目录dist。该位置可以通过 build.outDir 配置修改，如果你的项目改了outDir，只需将下文各平台指南中的dist替换为实际目录即可。
  • 使用 npm。如果你使用 Yarn 或其他包管理器，执行等价脚本命令即可。
  • Vite 作为本地开发依赖安装在项目中，且package.json中配置了如下两个脚本：
{ "scripts": { "build": "vite build", "preview": "vite preview" } }

需要特别强调的一点：vite preview仅用于在本地预览生产构建，并不适合作为生产服务器使用。它模拟的是“生产部署”的静态服务行为，而不是一个为线上流量设计的服务器。

此外，这篇指南针对的是静态部署。Vite 同时支持服务端渲染（SSR）——即让同一应用运行在 Node.js 中、预渲染为 HTML、再在客户端 hydrate。如果你的需求是 SSR，应查阅 SSR 指南；如果要将 Vite 与传统服务端框架集成，则应查阅 Backend Integration 指南。

构建应用：npm run build

执行构建命令：

$ npm run build

默认情况下，构建产物输出到项目根目录下的dist文件夹。这个dist目录就是你要部署到任何目标平台的静态站点产物（index.html、打包后的 JS/CSS 与处理过的资源）。

本地验证构建：vite preview 的原理与用法

构建完成后，在本地验证生产构建是否可用是最关键的一步：

$ npm run preview

vite preview会启动一个本地静态服务器，从dist目录提供文件，默认地址为http://localhost:4173。这是确认生产构建在本地表现是否符合预期的简便方式。

preview 服务器的源码实现

从源码看，preview 服务器的实现位于 packages/vite/src/node/preview.ts，几个值得了解的细节都能直接印证文档行为：

  1. 默认端口 4173 来自常量定义。在 packages/vite/src/node/constants.ts 中有DEFAULT_PREVIEW_PORT = 4173，这正是文档所说的默认预览端口。

  2. preview 继承 server 配置，但默认端口独立。resolvePreviewOptions函数会继承几乎所有CommonServerOptions（host、https、proxy、cors、headers 等），唯独端口默认回落到 4173——源码注释说明这是为了让开发服务器和预览服务器能同时运行而互不冲突。

  3. 它会真实地服务 dist 目录。preview()内部先通过resolveConfig(inlineConfig, 'serve', 'production', 'production', true)以生产模式解析配置，然后定位config.environments.client.build.outDir对应的distDir，使用sirv中间件从该目录提供静态文件。如果该目录不存在且没有插件实现configurePreviewServer，CLI 会直接抛出The directory "..." does not exist. Did you build your project?的错误——这也解释了为什么必须先npm run build再npm run preview。

  4. SPA 路由回退是内置的。当appType为spa或mpa时，会挂载htmlFallbackMiddleware，将未命中静态资源的路径回退到index.html。这意味着像单页应用这种带客户端路由的项目在 preview 下刷新任意路由也能正常工作，而不是一律 404。

修改预览端口

通过--port参数可以指定服务器端口：

{ "scripts": { "preview": "vite preview --port 8080" } }

配置后preview命令就会在http://localhost:8080上启动。

GitHub Pages 部署

1. 更新 Vite 配置：正确设置 base

在vite.config.js中设置正确的base：

  • 如果部署到https://<USERNAME>.github.io/，或者通过 GitHub Pages 使用自定义域名（如www.example.com），则将base设为'/'。你也可以直接删掉配置中的base，因为它默认就是'/'。
  • 如果部署到https://<USERNAME>.github.io/<REPO>/（即仓库地址为https://github.com/<USERNAME>/<REPO>），则将base设为'/<REPO>/'。

关于base的更多细节可参见 共享配置选项中的 base 说明：它的类型是string，默认值为/，合法取值包括绝对 URL pathname（如/foo/）、完整 URL（如https://bar.com/foo/，开发时 origin 部分不生效）、空字符串或./（用于嵌入式部署）。

2. 启用 GitHub Pages

在仓库中进入Settings → Pages，在Build and deployment区域展开Source下拉菜单，选择GitHub Actions。这样 GitHub 会通过 GitHub Actions 工作流部署你的站点——对 Vite 项目这是必需的，因为部署前必须经过构建步骤。

3. 创建工作流文件

在仓库中创建.github/workflows/deploy.yml（上一步界面中的 “create your own” 链接也可以帮你生成一个初始工作流文件）。以下是一个示例工作流：它使用 npm 安装依赖、构建站点，并在每次向main分支推送时部署（以下内容对应仓库中的 static-deploy-github-pages.yaml）：

# Simple workflow for deploying static content to GitHub Pages name: Deploy static content to Pages on: # Runs on pushes targeting the default branch push: branches: ['main'] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages permissions: contents: read pages: write id-token: write # Allow one concurrent deployment concurrency: group: 'pages' cancel-in-progress: true jobs: # Single deploy job since we're just deploying deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up Node uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 with: node-version: lts/* cache: 'npm' - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Setup Pages uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6 - name: Upload artifact uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 with: # Upload dist folder path: './dist' - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

工作流要点：permissions授予pages: write与id-token: write以允许部署到 Pages；concurrency保证同一时间只有一个部署在运行；Upload artifact步骤显式上传./dist目录，与 Vite 的默认outDir对应。如果项目修改了build.outDir，这里的path也要同步修改。

GitLab Pages 与 GitLab CI 部署

  1. 在vite.config.js中设置正确的base：

    • 部署到https://<USERNAME or GROUP>.gitlab.io/时，可以省略base（默认'/'）；
    • 部署到https://<USERNAME or GROUP>.gitlab.io/<REPO>/（例如仓库位于https://gitlab.com/<USERNAME>/<REPO>）时，将base设为'/<REPO>/'。

  2. 在项目根目录创建.gitlab-ci.yml，内容如下。它会在你的默认分支有变更时构建并部署站点：

image: node:lts pages: stage: deploy cache: key: files: - package-lock.json prefix: npm paths: - node_modules/ script: - npm install - npm run build - cp -a dist/. public/ artifacts: paths: - public rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

注意 GitLab Pages 的特殊点：CI 产物需要放在public目录（cp -a dist/. public/），而不是像其他平台一样直接指向dist。

Netlify 部署

使用 Netlify CLI

  1. 通过npm install -g netlify-cli安装 Netlify CLI。
  2. 使用netlify init创建新站点。
  3. 使用netlify deploy部署。

CLI 会给你一个预览 URL 供检查。确认无误后，加上prod标志进入生产环境：netlify deploy --prod。

通过 Git 集成 Netlify

  1. 将代码推送到 git 仓库（GitHub、GitLab、BitBucket、Azure DevOps）。
  2. 在 Netlify 上导入项目。
  3. 选择分支、输出目录，并在适用时配置环境变量。
  4. 点击Deploy。
  5. 你的 Vite 应用即完成部署。

导入并部署后，后续所有向非生产分支的推送以及 Pull Request 都会生成 Preview Deployments（预览部署），而对生产分支（通常是 “main”）的变更则触发 Production Deployment（生产部署）。

Vercel 部署

使用 Vercel CLI

  1. 通过npm i -g vercel安装 Vercel CLI，运行vercel即可部署。
  2. Vercel 会自动检测到你在使用 Vite，并为部署启用正确的默认设置。
  3. 应用部署完成。

通过 Git 集成 Vercel

  1. 将代码推送到你的 git 仓库（GitHub、GitLab、Bitbucket）。
  2. 在 Vercel 上导入你的 Vite 项目。
  3. Vercel 会自动识别 Vite 并启用正确的部署设置。
  4. 应用部署完成。

与 Netlify 类似，项目导入部署后，向分支的后续推送会生成预览部署，对生产分支（通常是 “main”）的变更则生成生产部署。

Cloudflare 部署

Cloudflare Workers

Cloudflare Vite 插件提供了与 Cloudflare Workers 的集成，并利用 Vite 的 Environment API 在开发期间将你的服务端代码运行在 Cloudflare Workers 运行时中。

要在现有 Vite 项目中加入 Cloudflare Workers，安装插件并加入配置：

$ npm install --save-dev @cloudflare/vite-plugin
import { defineConfig } from 'vite' import { cloudflare } from '@cloudflare/vite-plugin' export default defineConfig({ plugins: [cloudflare()], })
{ "name": "my-vite-app", }

执行npm run build之后，即可通过npx wrangler deploy部署应用。该插件还支持为 Vite 应用添加后端 API，以便安全地访问 Cloudflare 资源——开发时运行在 Workers 运行时中，并与前端一起部署。

Cloudflare Pages

Cloudflare Pages 提供了一条无需维护 Wrangler 配置文件即可直接部署到 Cloudflare 的路径。通过 Git 集成的步骤：

  1. 将代码推送到 git 仓库（GitHub、GitLab）。
  2. 登录 Cloudflare 控制台，在Account Home>Workers & Pages中选择你的账户。
  3. 选择Create a new Project与Pages选项，然后选择 Git。
  4. 选择要部署的 git 项目，点击Begin setup。
  5. 根据你使用的 Vite 框架选择对应的框架预设；否则手动填入构建命令和预期输出目录。
  6. 保存并部署。
  7. 应用部署完成（例如https://<PROJECTNAME>.pages.dev/）。

导入部署后，向分支的后续推送会生成预览部署（除非在分支构建控制中关闭），对生产分支的变更触发生产部署。Pages 还支持自定义域名和自定义构建设置。

Google Firebase 部署

  1. 通过npm i -g firebase-tools安装 firebase-tools。
  2. 在项目根目录创建以下两个文件：
{ "hosting": { "public": "dist", "ignore": [], "rewrites": [ { "source": "**", "destination": "/index.html" } ] } }
{ "projects": { "default": "<YOUR_FIREBASE_ID>" } }

其中rewrites将所有路径重写至/index.html，这正是 SPA 客户端路由刷新不 404 的关键——与上文 preview 服务器内置的 HTML fallback 行为对应。

  1. 执行npm run build之后，使用firebase deploy部署。

Surge 部署

  1. 通过npm i -g surge安装 surge。
  2. 运行npm run build。
  3. 输入surge dist部署到 surge。

也可以通过surge dist yourdomain.com部署到自定义域名。

Azure Static Web Apps 部署

使用微软 Azure Static Web Apps 服务可以快速部署 Vite 应用，你需要：

  • 一个 Azure 账户和订阅密钥（可创建免费账户）；
  • 应用代码已推送到 GitHub；
  • Visual Studio Code 中安装 SWA 扩展。

在 VS Code 中安装扩展并打开应用根目录，打开 Static Web Apps 扩展，登录 Azure，点击 “+” 创建新的 Static Web App，并按提示指定要使用的订阅密钥。

跟随向导为应用命名、选择框架预设，并指定应用根目录（通常是/）和构建产物位置/dist。向导会在仓库的.github目录中创建一个 GitHub Action。

该 Action 会负责部署应用（可在仓库 Actions 页签查看进度），部署成功后即可通过扩展进度窗口中出现的 “Browse Website” 按钮查看应用。

Render 部署

可以将 Vite 应用作为 Static Site 部署到 Render：

  1. 注册 Render 账户。
  2. 在 Dashboard 中点击New按钮，选择Static Site。
  3. 连接 GitHub/GitLab 账户或使用公共仓库。
  4. 指定项目名称和分支：
    • Build Command：npm install && npm run build
    • Publish Directory：dist
  5. 点击Create Static Site。应用将部署到https://<PROJECTNAME>.onrender.com/。

默认情况下，向指定分支推送任何新提交都会自动触发新的部署，自动部署行为可以在项目设置中配置。项目也支持添加自定义域名。

其他平台

除上述详细平台外，官方指南还列出了几个可直接按其平台文档部署 Vite 静态站点的选项：

  • Flightcontrol：按其官方文档中的 Vite 示例步骤部署静态站点。
  • xmit Static Site Hosting：按照其 Vite quickstart 指南部署。
  • Zephyr Cloud：一个直接集成进构建流程的部署平台，为全球边缘提供模块联邦等应用的分发。与其他云提供商不同，Zephyr 直接与 Vite 构建过程集成——每次你为应用执行构建或运行 dev server 时，都会自动通过 Zephyr Cloud 部署。
  • EdgeOne Pages：按其 Vite 部署文档的说明部署静态站点。

小结：静态部署的通用心法

回顾整篇指南，所有平台的部署差异其实集中在三点：

  1. 产物目录：几乎都是dist（build.outDir默认值），GitLab Pages 例外，需要复制到public。
  2. base 路径：部署在站点根路径时保持默认'/'即可；部署在子路径（如 GitHub Pages 的/<REPO>/）时必须显式设置base。
  3. 构建步骤：托管平台需要通过 CLI 手动执行npm run build，或通过 CI/CD（GitHub Actions、GitLab CI、平台 Git 集成）在部署前自动完成构建；部署前建议先用vite preview在本地验证生产构建，尤其是 SPA 路由回退与资源路径是否符合预期。

【免费下载链接】viteNext generation frontend tooling. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

Godot 引擎 C 脚本诊断规则全解：从 Godot.SourceGenerators 的 AnalyzerReleases.Shipped.md 读懂 GD 系列报错
2026/9/5 19:22:10 网站建设

Godot 引擎 C 脚本诊断规则全解：从 Godot.SourceGenerators 的 AnalyzerReleases.Shipped.md 读懂 GD 系列报错

Godot 引擎 C# 脚本诊断规则全解&#xff1a;从 Godot.SourceGenerators 的 AnalyzerReleases.Shipped.md 读懂 GD 系列报错 【免费下载链接】godot Godot Engine – Multi-platform 2D and 3D game engine 项目地址: https://gitcode.com/GitHub_Trending/go/godot 本文…...

阅读更多 →
用系统思维拆解偏激暴食：越控制为何越失控？
2026/9/5 19:19:43 网站建设

用系统思维拆解偏激暴食：越控制为何越失控？

你点开这篇文章&#xff0c;大概率不是想学一道减脂餐&#xff0c;也不是想收藏一份热量表。你可能是那个白天严格自律、深夜却控制不住点开外卖软件的人&#xff0c;也可能是那个每次吃完都发誓“明天开始重新做人”的人。把这个话题放在技术社区里聊&#xff0c;听起来有点奇…...

阅读更多 →
Faster-Whisper 本地语音识别部署与推理加速完整指南：5分钟跑通第一条转录
2026/9/5 19:15:02 网站建设

Faster-Whisper 本地语音识别部署与推理加速完整指南：5分钟跑通第一条转录

Faster-Whisper 本地语音识别部署与推理加速完整指南&#xff1a;5分钟跑通第一条转录 【免费下载链接】faster-whisper Faster Whisper transcription with CTranslate2 项目地址: https://gitcode.com/GitHub_Trending/fa/faster-whisper 云端 ASR 按量计费&#xff0…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询