Vite（三）部署静态站点（wordpress与hugo与Vercel、CI/CD、Travis CI、GitLab CI）、环境变量与模式、服务端渲染（SSR）

文章目录

Vite（三）部署静态站点（wordpress与hugo与Vercel、CI/CD、Travis CI、GitLab CI）、环境变量与模式、服务端渲染（SSR）
- 1. 部署静态站点
- - 构建应用
  - - 本地测试应用
  - GitHub Pages
  - - GitHub Pages 配合 Travis CI
  - GitLab Pages 配合 GitLab CI
  - Netlify
  - Google Firebase
  - Surge
  - Heroku
  - Vercel
- 2. 环境变量与模式
- - 环境变量
  - - 生产环境替换
  - `.env` 文件
  - 模式
- 3. 服务端渲染
- - 示例项目
  - 源码结构
  - 情景逻辑
  - 设置开发服务器
  - 生产环境构建
  - 生成预加载指令
  - 预渲染 / SSG
  - SSR 外部化
  - SSR 专有插件逻辑

网址：https://vitejs.cn/guide/why.html

1. 部署静态站点

hugo跟wordpress其他建站工具的对比
- wordpress 全球31%的网站使用wordpress，尽管他有各种主题和插件，但是也有非常多的缺点，安全性，seo不够友好，定制麻烦
- hugo hexo最快的静态生成工具,seo友好，静态更安全，方便定制模板，缺点没有插件，如果要定制模板只能懂一点go的语法
- wordpress是动态的并且还需要托管数据库，所以托管费用比较昂贵
- 两个静态网页生成器：hexo和hugo。在使用两者之前就有将两者进行过对比，前者基于 node.js、后者基于 golang
- hugo hexo是生成静态的页面，在本地生成后上传到服务器就可以了，托管费用非常便宜，可以直接用免费的github托管

下面的指引都基于以下几个假设：

你正在使用的是默认的构建输出路径（dist）。这个路径可以使用 build.outDir 更改，在这种情况下，你可以从这篇指南中推断出所需的指令。
Vite 已经被安装为了一个你项目的本地开发依赖（dev dependency），并且你已经配置好了如下的 npm script：
你正在使用 npm，或者使用了 Yarn 或其他的包管理工具，可以运行下面的脚本指令：

{"scripts": {"build": "vite build","preview": "vite preview"}
}

值得注意的是 vite preview 旨在提供一个生产版本的本地预览，但不应直接作为一个生产服务器。

注意

本篇指引提供的指令旨在本篇指南提供了如何执行 Vite 站点的静态部署的说明。Vite 也对服务端渲染（SSR）有了实验性的支持。SSR 是指支持在 Node 中运行相应应用的前端框架，预渲染成 HTML，最后在客户端激活（hydrate）。查看 SSR 指南可以了解更多细节。另一方面，如果你正在寻找与传统服务端框架集成的方式，那么请查看后端集成章节。

构建应用

你可以运行 npm run build 命令来执行应用的构建。

$ npm run build

默认情况下，构建会输出到 dist 文件夹中。你可以部署这个 dist 文件夹到任何你喜欢的平台。

本地测试应用

当你构建完成应用后，你可以通过运行 npm run preview 命令，在本地测试该应用。

$ npm run build
$ npm run preview

preview 命令会启动一个本地静态 Web 服务器，将 dist 文件夹运行在 http://localhost:5000 上。这样在本地查看该产物是否正常可用就十分容易了。

你可以使用 --port 标志传入一个参数来配置服务器的运行端口。

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

这样 preview 命令会改将服务器运行在 http://localhost:8080 上。

GitHub Pages

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

如果你要部署在 https://<USERNAME>.github.io/，你可以省略 base 因为其默认为 '/'。

如果你要部署在 https://<USERNAME>.github.io/<REPO>/，例如你的仓库地址为 https://github.com/<USERNAME>/<REPO>，那么请设置 base 为 '/<REPO>/'。
在你的项目中，创建一个 deploy.sh 脚本，包含以下内容（注意高亮的未注释的行)，运行它来部署站点：

#!/usr/bin/env sh# 发生任何错误时终止
set -e# 构建
npm run build# 进入输出产物文件夹
cd dist# 如果你要部署到自定义域名
# echo 'www.example.com' > CNAMEgit init
git add -A
git commit -m 'deploy'# 如果你要部署在 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master# 如果你要部署在 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pagescd -

TIP

你也可以在你的 CI 启动时运行该脚本，使得在每次推送代码时自动部署。

GitHub Pages 配合 Travis CI

Travis CI 提供的是持续集成服务（Continuous Integration，简称 CI）。它绑定 Github 上面的项目，只要有新的代码，就会自动抓取。然后，提供一个运行环境，执行测试，完成构建，还能部署到服务器。

持续集成指的是只要代码有变更，就自动运行构建和测试，反馈运行结果。确保符合预期以后，再将新代码"集成"到主干。

持续集成的好处在于，每次代码的小幅变更，就能看到运行结果，从而不断累积小的变更，而不是在开发周期结束时，一下子合并一大块代码。

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

如果你要部署在 https://<USERNAME or GROUP>.github.io/，你可以省略 base 因为其默认为 '/'。

如果你要部署在 https://<USERNAME or GROUP>.github.io/<REPO>/，例如你的仓库地址为 https://github.com/<USERNAME>/<REPO>，那么请设置 base 为 '/<REPO>/'。
在项目根目录创建一个 .travis.yml 文件
在本地运行 npm install 确认正常生成一个 lockfile (package-lock.json)。
使用 GitHub Pages 提供的部署模板，并跟随 Travis CI 文档进行配置：

language: node_js
node_js:- lts/*
install:- npm ci
script:- npm run build
deploy:provider: pagesskip_cleanup: truelocal_dir: dist# 在 GitHub 上生成的令牌，允许 Travis 推送代码到你的仓库。# 在仓库对应的 Travis 设置页面中配置，用于安全控制。github_token: $GITHUB_TOKENkeep_history: trueon:branch: master

GitLab Pages 配合 GitLab CI

CI，Continuous Integration，为持续集成。即在代码构建过程中持续地进行代码的集成、构建、以及自动化测试等；有了 CI 工具，我们可以在代码提交的过程中通过单元测试等尽早地发现引入的错误；
CD，Continuous Deployment，为持续交付。在代码构建完毕后，可以方便地将新版本部署上线，这样有利于快速迭代并交付产品。

GitLab CI/CD（后简称 GitLab CI）是一套基于 GitLab 的 CI/CD 系统，可以让开发人员通过 .gitlab-ci.yml 在项目中配置 CI/CD 流程，在提交后，系统可以自动/手动地执行任务，完成 CI/CD 操作。而且，它的配置非常简单，CI Runner 由 Go 语言编写，最终打包成单文件，所以只需要一个 Runner 程序、以及一个用于运行 jobs 的执行平台（如裸机+SSH，Docker 或 Kubernetes 等，我推荐用 Docker，因为搭建相当容易）即可运行一套完整的 CI/CD 系统。

在 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>/'。
在 vite.config.js 中设置 build.outDir 为 public。
在项目根目录创建一个 .gitlab-ci.yml 文件，包含以下内容。它将使得每次你更改内容时都重新构建与部署站点：

image: node:10.22.0
pages:cache:paths:- node_modules/script:- npm install- npm run buildartifacts:paths:- publiconly:- master

Netlify

一个静态网页的发布神器：叫做 Netlify。在它的主页上可以看到它的宣传语：用最快的方式构建最快的网站。确实快，而且免费。

在 Netlify 上，按下列设置配合 Github 设置好一个一个新的项目：

构建命令： vite build 或者 npm run build
发布目录： dist

点击部署按钮。

Google Firebase

FireBase官网(需要科学上网)

用官网简介的话来说就是：构建更出色应用和成功地扩大业务所需的工具和基础架构。

再次用官网的话描述：Firebase 是一个移动平台，可以帮助您快速开发高品质应用，扩大用户群，并赚取更多收益。Firebase 由多种互补功能组成，您可以自行组合和匹配这些功能以满足自己的需求。

最后总结一下：FireBase是一个用于构建移动应用、提供实时数据存储和同步、用户身份验证等功能的平台。因为是国外的东西，所有需要科学上网，请自备梯子。

确保已经安装 firebase-tools。
在项目根目录创建 firebase.json 和 .firebaserc 两个文件，应包含以下内容：

firebase.json:

{"hosting": {"public": "dist","ignore": []}
}

.firebaserc:

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

运行 npm run build 后，通过 firebase deploy 命令部署。

Surge

请确保您已经安装了 surge。
运行 npm run build。
通过运行 surge dist 命令部署到 surge。

你也可以通过添加 surge dist yourdomain.com 部署到一个自定义域名。

Heroku

在我们日常开发过程中，如果你想把自己的项目随意随时部署到生产环境，供自己或者他人共同测试、联调的话，那么Heroku绝对是您最优选择，它持久免费，操作简单，易于上手。

安装 Heroku CLI。
注册一个 Heroku 账号。
运行 heroku login 并填入你的你的 Heroku 凭证：

$ heroku login

在项目根目录创建一个 static.json ，应含以下内容：

static.json:

{"root": "./dist"
}

这是你站点的配置信息，阅读 heroku-buildpack-static 文档了解更多。

配置好你的 Heroku git 远程地址：

# 更新版本
$ git init
$ git add .
$ git commit -m "My site ready for deployment."# 创建一个具有指定名称的新应用
$ heroku apps:create example# 为静态站点设置 buildpack
$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git

部署站点：

# 发布站点
$ git push heroku master# 在浏览器中打开 Heroku CI 的仪表板
$ heroku open

Vercel

vercel是我用过的最好用的网站托管服务。本网站就是基于hexo引擎模板开发，托管在vercel上的。

vercel类似于github page，但远比github page强大，速度也快得多得多，而且将Github授权给vercel后，可以达到最优雅的发布体验，只需将代码轻轻一推，项目就自动更新部署了。

vercel还支持部署serverless接口。那代表着，其不仅仅可以部署静态网站，甚至可以部署动态网站，而这些功能，统统都是免费的，简直是白嫖党的福利啊！！！！！

vercel还支持自动配置https，不用自己去FreeSSL申请证书，更是省去了一大堆证书的配置，简直是懒人的福利啊啊啊有木有！

要通过 Vercel for Git 部署你的 Vite 应用，请确保它已经被推送为了一个 Git 仓库。

去往 https://vercel.com/import/git 并导入该项目到 Vercel，使用你相应地 Git 服务（GitHub，GitLab 或者 BitBucket）。根据指引，选择带有 package.json 的项目根目录。并使用 npm run build 来覆盖构建步骤，并将输出目录设置为 ./dist。

在项目被导入之后，所有后续的推送将生成预览部署，但只有对生产分支（通常是“main”）所做的所有更改才将触发生产部署。

一旦部署，你会得到一个 URL 来查看应用的实时预览，如 https://vite.vercel.app 。

2. 环境变量与模式

环境变量

Vite 在一个特殊的 import.meta.env 对象上暴露环境变量。这里有一些普遍适用的内建变量：

import.meta.env.MODE: string 应用运行基于的模式。
import.meta.env.BASE_URL: string 应用正被部署在的 base URL。它由 base 配置项决定。
import.meta.env.PROD: boolean 应用是否运行在生产环境
import.meta.env.DEV: boolean 应用是否运行在开发环境 (永远与 import.meta.env.PROD 相反)

生产环境替换

在生产环境中，这些环境变量会在构建时被静态替换，因此请在引用它们时使用完全静态的字符串。动态的 key 将无法生效。例如，动态 key 取值 import.meta.env[key] 是无效的。

它还将替换出现在 JavaScript 和 Vue 模板中的字符串。这应该是比较罕见的情况，但它可能是不小心为之。有一些方法可以避免这个问题:

对于 JavaScript 字符串，你可以在相应位置上使用一个 unicode 序列值，例如： 'import.meta\u200b.env.MODE'。
对于 Vue 模板或其他编译到 JavaScript 字符串的 HTML，你可以使用 `` 标签，例如：import.meta.<wbr>env.MODE。

`.env` 文件

Vite 使用 dotenv 在你的项目根目录下从以下文件加载额外的环境变量:

.env                # 所有情况下都会加载
.env.local          # 所有情况下都会加载，但会被 git 忽略
.env.[mode]         # 只在指定模式下加载
.env.[mode].local   # 只在指定模式下加载，但会被 git 忽略

加载的环境变量也会通过 import.meta.env 暴露给客户端源码。

为了防止意外地将一些环境变量泄漏到客户端，只有以 VITE_ 为前缀的变量才会暴露给经过 vite 处理的代码。例如下面这个文件中：

DB_PASSWORD=foobar
VITE_SOME_KEY=123

只有 VITE_SOME_KEY 会被暴露为 import.meta.env.VITE_SOME_KEY 提供给客户端源码，而 DB_PASSWORD 则不会。

安全警告

.env.*.local 文件应是本地的，可以包含敏感变量。你应该加上 .local 到你的 .gitignore 以避免他们被检出到 git。
由于暴露在 Vite 源码中的任何变量都将最终出现在客户端包中，VITE_* 变量应该不包含任何敏感信息。

模式

默认情况下，开发服务器 (serve 命令) 运行在 development （开发）模式，而 build 命令运行在 production （生产）模式。

这意味着当执行 vite build 时，它会自动加载 .env.production 中可能存在的环境变量：

# .env.production
VITE_APP_TITLE=My App

在你的应用中，你可以使用 import.meta.env.VITE_APP_TITLE 作为渲染标题。

然而重要的是，要理解模式是一个更广泛的概念，而不仅仅是开发和生产。一个典型的例子是，你可能希望有一个 “staging” 模式，它应该具有类似于生产的行为，但环境变量与生产环境略有不同。

你可以通过传递 --mode 选项标志来覆盖命令使用的默认模式。例如，如果你想为我们假设的 staging 模式构建应用:

vite build --mode staging

为了使应用实现预期行为，我们还需要一个 .env.staging 文件：

# .env.staging
NODE_ENV=production
VITE_APP_TITLE=My App (staging)

现在，staging 应用应该具有类似于生产的行为，但显示的标题与生产环境不同。

3. 服务端渲染

实验性

SSR 支持还处于试验阶段，你可能会遇到 bug 和不受支持的用例。请考虑你可能承担的风险。

注意

SSR 特别指支持在 Node.js 中运行相同应用程序的前端框架（例如 React、Preact、Vue 和 Svelte），将其预渲染成 HTML，最后在客户端进行脱水化处理。如果你正在寻找与传统服务器端框架的集成，请查看后端集成指南。

下面的指南还假定你在选择的框架中有使用 SSR 的经验，并且只关注特定于 vite 的集成细节。

帮助

如果你有疑问，可以到社区 Discord 的 Vite #ssr 频道，这里会帮到你。

示例项目

Vite 为==服务端渲染（SSR）==提供了内建支持。这里的 Vite 范例包含了 Vue 3 和 React 的 SSR 设置示例，可以作为本指南的参考：

Vue 3
React

源码结构

一个典型的 SSR 应用应该有如下的源文件结构：

- index.html
- src/- main.js          # 导出环境无关的（通用的）应用代码- entry-client.js  # 将应用挂载到一个 DOM 元素上- entry-server.js  # 使用某框架的 SSR API 渲染该应用

index.html 将需要引用 entry-client.js 并包含一个占位标记供给服务端渲染时注入：

<div id="app"><!--ssr-outlet--></div>
<script type="module" src="/src/entry-client.js"></script>

你可以使用任何你喜欢的占位标记来替代 ，只要它能够被正确替换。

情景逻辑

如果需要基于 SSR 和 client 执行情景逻辑，可以使用：

if (import.meta.env.SSR) {// ... 仅在服务端的逻辑
}

这是在构建过程中被静态替换的，因此它将允许对未使用的条件分支进行摇树优化。

设置开发服务器

在构建 SSR 应用程序时，你可能希望完全控制主服务器，并将 Vite 与生产环境解耦。因此，建议以中间件模式使用 Vite。下面是一个关于 express 的例子：

server.js

const fs = require('fs')
const path = require('path')
const express = require('express')
const { createServer: createViteServer } = require('vite')async function createServer() {const app = express()// 以中间件模式创建 vite 应用，这将禁用 Vite 自身的 HTML 服务逻辑// 并让上级服务器接管控制const vite = await createViteServer({server: { middlewareMode: true }})// 使用 vite 的 Connect 实例作为中间件app.use(vite.middlewares)app.use('*', async (req, res) => {// 服务 index.html - 下面我们来处理这个问题})app.listen(3000)
}createServer()

这里 vite 是 ViteDevServer 的一个实例。vite.middlewares 是一个 Connect 实例，它可以在任何一个兼容 connect 的 Node.js 框架中被用作一个中间件。

下一步是实现 * 处理程序供给服务端渲染的 HTML：

app.use('*', async (req, res) => {const url = req.originalUrltry {// 1. 读取 index.htmllet template = fs.readFileSync(path.resolve(__dirname, 'index.html'),'utf-8')// 2. 应用 vite HTML 转换。这将会注入 vite HMR 客户端，and//    同时也会从 Vite 插件应用 HTML 转换。//    例如：@vitejs/plugin-react-refresh 中的 global preamblestemplate = await vite.transformIndexHtml(url, template)// 3. 加载服务器入口。vite.ssrLoadModule 将自动转换//    你的 ESM 源码将在 Node.js 也可用了！无需打包//    并提供类似 HMR 的根据情况随时失效。const { render } = await vite.ssrLoadModule('/src/entry-server.js')// 4. 渲染应用的 HTML。这假设 entry-server.js 导出的 `render`//    函数调用了相应 framework 的 SSR API。//    例如 ReactDOMServer.renderToString()const appHtml = await render(url)// 5. 注入应用渲染的 HTML 到模板中。const html = template.replace(`<!--ssr-outlet-->`, appHtml)// 6. 将渲染完成的 HTML 返回res.status(200).set({ 'Content-Type': 'text/html' }).end(html)} catch (e) {// 如果捕获到了一个错误，让 vite 来修复该堆栈，这样它就可以映射回// 你的实际源码中。vite.ssrFixStacktrace(e)console.error(e)res.status(500).end(e.message)}
})

package.json 中的 dev 脚本也应该相应地改变，使用服务器脚本：

  "scripts": {-   "dev": "vite"
+   "dev": "node server"}

生产环境构建

为了将 SSR 项目交付生产，我们需要：

正常生成一个客户端构建；
再生成一个 SSR 构建，可以通过 require() 直接加载因此我们无需再经过 Vite 的 ssrLoadModule；

package.json 中的脚本应该看起来像这样：

{"scripts": {"dev": "node server","build:client": "vite build --outDir dist/client","build:server": "vite build --outDir dist/server --ssr src/entry-server.js "}
}

注意使用 --ssr 标志表明这将会是一个 SSR 构建。它也应该能指明 SSR 入口。

接着，在 server.js 中，通过检出 process.env.NODE_ENV 我们需要添加一些生产环境特定的逻辑：

使用 dist/client/index.html 作为模板，而不是读取根目录的 index.html，因为它包含了到客户端构建的正确资源链接。
使用 require('./dist/server/entry-server.js') ，而不是 await vite.ssrLoadModule('/src/entry-server.js')（该文件是 SSR 构建的最终结果）。
将 vite 开发服务器的创建和所有使用都移到 dev-only 条件分支后面，然后添加静态文件服务中间件来服务 dist/client 中的文件。

可以在此参考 Vue 和 React 的启动范例。

生成预加载指令

vite build 支持使用 --ssrManifest 标志，这将会在构建输出目录中生成一份 ssr-manifest.json：

- "build:client": "vite build --outDir dist/client",
+ "build:client": "vite build --outDir dist/client --ssrManifest",

上面的脚本现在将会为客户端构建生成 dist/client/ssr-manifest.json（是的，该 SSR 清单是从客户端构建生成而来，因为我们想要将模块 ID 映射到客户端文件上）。清单包含模块 ID 到它们关联的 chunk 和资源文件的映射。

为了利该清单，框架需要提供一种方法来收集在服务器渲染调用期间使用到的组件模块 ID。

@vitejs/plugin-vue 支持该功能，开箱即用，并会自动注册使用的组件模块 ID 到相关的 Vue SSR 上下文：

// src/entry-server.js
const ctx = {}
const html = await vueServerRenderer.renderToString(app, ctx)
// ctx.modules 现在是一个渲染期间使用的模块 ID 的 Set

我们现在需要在 server.js 的生产情景分支下读取该清单，并将其传递到 src/entry-server.js 导出的 render 函数中，这将为我们提供足够的信息，来为异步路由相应的文件渲染预加载指令！查看示例代码获取完整示例。

预渲染 / SSG

如果预先知道某些路由所需的路由和数据，我们可以使用与生产环境 SSR 相同的逻辑将这些路由预先渲染到静态 HTML 中。这也被视为一种静态站点生成（SSG）的形式。查看示例渲染代码获取有效示例。

SSR 外部化

许多依赖都附带 ESM 和 CommonJS 文件。当运行 SSR 时，提供 CommonJS 构建的依赖关系可以从 Vite 的 SSR 转换/模块系统进行 “外部化”，从而加速开发和构建。例如，并非去拉取 React 的预构建的 ESM 版本然后将其转换回 Node.js 兼容版本，用 require('react') 代替会更有效。它还大大提高了 SSR 包构建的速度。

Vite 基于以下启发式执行自动化的 SSR 外部化:

如果一个依赖的解析 ESM 入口点和它的默认 Node 入口点不同，它的默认 Node 入口可能是一个可以外部化的 CommonJS 构建。例如，vue 将被自动外部化，因为它同时提供 ESM 和 CommonJS 构建。
否则，Vite 将检查包的入口点是否包含有效的 ESM 语法 - 如果不包含，这个包可能是 CommonJS，将被外部化。例如，react-dom 将被自动外部化，因为它只指定了唯一的一个 CommonJS 格式的入口。

如果这个启发式导致了错误，你可以通过 ssr.external 和 ssr.noExternal 配置项手动调整。

在未来，这个启发式将可能得到改进，将去探测该项目是否有启用 type: "module"，因而 Vite 也可以外部化兼容 Node 的 ESM 构建依赖。（并在服务端渲染时使用动态 import() 引入它们）。

使用别名

如果你为某个包配置了一个别名，为了能使 SSR 外部化依赖功能正常工作，你可能想要使用的别名应该指的是实际的 node_modules 中的包。Yarn 和 pnpm 都支持通过 npm: 前缀来设置别名。

SSR 专有插件逻辑

一些框架，如 Vue 或 Svelte，会根据客户端渲染和服务端渲染的区别，将组件编译成不同的格式。可以向以下的插件钩子中，给 Vite 传递额外的 ssr 参数来支持根据情景转换：

resolveId
load
transform

示例：

export function mySSRPlugin() {return {name: 'my-ssr',transform(code, id, ssr) {if (ssr) {// 执行 ssr 专有转换...}}}
}