Vue3 Vite3 多環境配置 - 基於 vite 創建 vue3 全家桶項目(續篇）

Vue3 Vite3 多環境配置 – 基於 vite 創建 vue3 全家桶項目(續篇）

2022 年 10 月 6 日
筆記
vite, VUE, vue3, 前端, 多環境配置

在項目或產品的迭代過程中，通常會有多套環境，常見的有：

dev：開發環境
sit：集成測試環境
uat：用戶接收測試環境
pre：預生產環境
prod：生產環境

環境之間配置可能存在差異，如接口地址、全局參數等。在基於 vue-cli （webpack） 的項目中只需要添加 .env.xxx 文件，然後在 package.json 的 scripts 啟動或打包命令中指定 mode 參數即可，獲取環境變量時使用 process.env.xxx。vite 使用方式類似，但獲取環境變量使用 import.meta.env。

1 環境變量和模式

上面提到，vite 中使用 import.meta.env 的方式來獲取環境變量。在 main.ts 中添加如下代碼進行測試：

const env = import.meta.env
console.log(env)

1.1 development

首先執行 yarn dev 啟動服務，在瀏覽器控制台輸出 env 的值：

可以看出 import.mata.env 中默認包括五個內置環境變量：

MODE：應用的運行模式。由於我們是通過 yarn dev 啟動服務，而 yarn dev 本質是執行 vite 啟動，未顯式執行 mode，故 MODE 的值為 development；

BASE_URL：部署應用時的基本 URL，在 vite 的配置文件 vite.config.ts 中的 base 屬性指定；

PROD：是否是生產環境（即是否通過 vite build 構建）

DEV：是否是開發環境（即是否通過 vite 啟動服務運行）

SSR：是否是服務端渲染模式。

1.2 production

首先執行 yarn build 打包（本質上是執行 vite build），打包完成後通過 yarn preview 對打包結果進行預覽。訪問預覽地址，在瀏覽器控制塔輸出如下：

可以看出模式為 production，非開發模式，是生產模式。

1.3 指定模式

修改 package.json 中的 scripts 命令，分別為開發和打包指定三種模式：dev、uat、prod。指定模式只需要在命令後通過參數 –mode 指定即可。

"scripts": {
  "dev": "yarn dev:dev",
  "dev:dev": "vite --mode dev",
  "dev:uat": "vite --mode uat",
  "dev:prod": "vite --mode prod",
  "build:dev": "vue-tsc --noEmit && vite build --mode dev",
  "build:uat": "vue-tsc --noEmit && vite build --mode uat",
  "build:prod": "vue-tsc --noEmit && vite build --mode prod",
  "preview": "vite preview"
},

執行 yarn dev:dev，瀏覽器輸出 MODE： dev；

執行 yarn dev:uat，瀏覽器輸出 MODE： uat；

執行 yarn dev:prod，瀏覽器輸出 MODE： prod；

接下來依次通過 build:xxx 先打包後再通過 preview 預覽打包，結果與上面一致，瀏覽器輸出的 MODE 與命令中 –mode 指定的值一致。

2 環境文件（.env）

Vite 使用 dotenv 從 環境文件目錄 中加載環境文件，默認情況下，環境文件目錄為項目的根目錄，即把環境文件放在項目根目錄下。在 vite 中，可以通過配置 envDir 屬性指定環境文件目錄。

2.1 指定環境文件目錄

在項目根目錄下創建目錄 env，用於存放所有的環境文件。

在 vite.config.ts 中添加 envDir 屬性指定環境文件目錄為 env：

...
export default defineConfig({
  ...
  envDir: path.resolve(__dirname, './env')
})

2.2 添加環境文件

環境文件命名如下：

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

不同環境的變量可以定義在 .env.[mode] 文件中，如 .env.dev、.env.prod 等，如果 .env 文件和 .env.[mode] 中有相同的 key，後者定義的值會覆蓋前者。

這裡咱們以三個環境為例編寫 demo，分別是：

開發環境，mode 為 dev，文件名為 .env.dev
測試環境，mode 為 uat，文件名為 .env.uat
生產環境，mode 為 prod，文件名為 .env.prod

在上面指定的環境文件目錄 env 下創建上面三個文件，以及所有情況下都會加載的 .env 文件。四個文件內容如下：

.env 文件

VITE_BASE_API=/api
VITE_APP_NAME='demo app'
DEMO_STR=hello

.env.dev 文件

VITE_BASE_API=/dev-api

.env.uat 文件

VITE_BASE_API=/uat-api

.env.prod 文件

VITE_BASE_API=/prod-api

四個文件都定義了變量 VITE_BASE_API，.env 中還額外定義了 VITE_APP_NAME 和 DEMO_STR 兩個變量。

使用 yarn dev:dev 啟動服務，或者先使用 yarn build:dev 打包，再通過 yarn preview 預覽打包結果，瀏覽器中都會輸出 VITE_BASE_API 和 VITE_APP_NAME 的值。VITE_BASE_API 值為 .env.dev 中定義的 /dev-api，VITE_APP_NAME 值為 .env 中定義的 demo app，但是 .env 中定義的 DEMO_STR 不會輸出。由此可以看出：

無論是哪種模式，.env 文件都會被加載；
如果 .env.[mode] 和 .env 中有相同的 key，對應模式的環境文件中的值會覆蓋 .env 對應 key 的值；
環境變量需要以 VITE_ 開頭才會暴露到 import.meta.env 中。

有興趣的朋友可以再添加 .env.dev.local 文件進行測試，.env.[mode].local 優先級最高。

3 TypeScript 提示

我使用的 IDE 是 WebStorm，之前在 main.ts 中將 import.meta.env 賦值給變量 env：

const env = import.meta.env

輸入 env.，WebStorm會有下圖中的提示：

但是沒有提示我們添加的環境變量。可以添加 env.d.ts 解決。在 src 目錄下創建文件 env.d.ts，文件內容如下：

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_BASE_API: string;
  readonly VITE_APP_NAME: string;
}

// eslint-disable-next-line no-unused-vars
interface ImportMeta {
  readonly env: ImportMetaEnv
}

在 ImportMetaEnv 中添加上環境文件中定義的變量即可。

此時再次在 main.ts 中輸入 env.，IDEA便可以有正確的代碼提示，並且可以獲取該變量的類型：

4 補充說明

在基於 vue-cli（webpack） 的項目中獲取環境變量是通過 process.env.xxx 的方式，如果不進行配置，在瀏覽器中會報錯，提示 process is undefine。於是我按照網上的方式，在 vite.config.ts 中首先通過 vite 提供的 loadEnv 函數加載環境變量，然後在導出對象中添加 define 屬性，在 define 中將 loadEnv 返回的結果賦值給 process.env，如下：

define: {
  'process.env': loadEnv(env.mode, process.cwd(), '')
}

通過這種方式，在開發模式下（vite 啟動服務）,可以正常獲取到環境變量，甚至環境變量不要求以 VITE_ 開頭。但是使用 vite build 打包一直失敗，在使用了 process.env 提示 parse error，到現在也不知道怎麼處理。如果知道怎麼處理的夥伴歡迎留言。

不過個人更推薦按照官方的方式，使用 import.meta.env 。

文中 demo 在 github 上搜索 vue3-vite-archetype 獲取，main 分支可以直接 yarn dev 啟動運行； template 分支是 yyg-cli 執行 yyg create 創建項目時拉取的模板。你也可以先執行 npm install -g yyg-cli 安裝 yyg-cli 腳手架工具，然後通過 yyg create xxx 創建項目，創建後的項目包含了 vue3 vite 的全部demo。

Tags: vite VUE vue3 前端多環境配置