環境變數

環境變數是一種儲存應用程式程式碼中不應直接包含的組態值或敏感資料的方法。這些變數通常用於 API 金鑰、資料庫連線字串或其他環境特定的設定。

環境變數的類型

建置時

環境變數會以 PUBLIC_ 作為開頭，並且在 client 和 server 端都可以使用。

伺服器端

環境變數只能在 server 端存取。

重要！請勿使用 建置時 環境變數（例如以 PUBLIC_ 開頭的變數）來儲存任何敏感資訊，例如 API 金鑰、密碼、密碼等等。這些變數在瀏覽器中是公開資料。

.env.local

# This will only be available when run on the server
API_KEY=secretApiKeyHere
# This will be available everywhere
PUBLIC_API_URL=https://api.example.com

預設環境變數

QwikCity 預設包含了一些環境變數

BASE_URL: string - 返回頁面的基本網址
MODE: string - 返回渲染模式
DEV: boolean - 返回是否處於開發模式
PROD: boolean - 返回是否處於生產環境模式
SSR: boolean - 返回是否使用 ssr 進行渲染

在 QwikCity 中存取環境變數的首選方法是透過 import.meta.env.*（客戶端）或在伺服器端執行時透過 Request 物件。

process.env 是 Node.js 專屬的 API，應盡一切可能避免使用。

建置時變數

建置時變數由 Vite 提供支援。它們定義在 .env 檔案中，並且在瀏覽器和伺服器端程式碼中都可用。

請注意，建置時變數應被視為公開的，因為它們將被硬編碼到瀏覽器建置中，任何人都可以輕鬆讀取。

建置時變數預設以 PUBLIC_ 為前綴，並且可以使用 import.meta.env.PUBLIC_* 進行存取。

定義變數

.env.local

PUBLIC_API_URL=https://api.example.com

用法

src/routes/index.tsx

import { component$ } from '@builder.io/qwik';
 
export default component$(() => {
  // `import.meta.env.PUBLIC_*` variables can be read anywhere, including browser
  return <div>PUBLIC_API_URL: {import.meta.env.PUBLIC_API_URL}</div>
})

import.meta.env.PUBLIC_* 變數可以在任何地方讀取，但不要在其中放置任何敏感資訊，因為客戶端將可以看到它們。

伺服器端變數

伺服器端變數基本上是僅在伺服器端程式碼中可用的執行時變數。

它們在建置時是未知的，並且在瀏覽器中不可用，因此可以將它們視為私有的。

在生產環境中，設定伺服器端變數的方法會因平台而異。大多數平台都允許您從其控制面板或 CLI 設定環境變數。如需更多資訊，請參閱您的平台（cloudflare、vercel、netlify）文件。

Docker 和 Fastify 的特殊注意事項:

Docker：雖然 Docker 允許直接在 Dockerfile 中包含環境變數，但這種方法可能會洩露敏感資料。更安全的做法是在執行時使用 Docker Compose 管理這些變數。例如
docker-compose.yml
version: '3.8'
services:
 your-service:
   image: your-image-name
   environment:
     - FOO=BAR
Docker 中的 Fastify：當使用 Fastify 時，放置在 .env 或 .env.local 檔案中的環境變數可能無法在生產環境中自動辨識。為了讓這些設定生效，可能需要在 Fastify 應用程式中明確載入它們，或透過 Docker 的環境管理系統（Docker Compose）傳遞它們，如上所示。

定義變數

.env.local

DB_PRIVATE_KEY=123456789

請確保您永遠不要將 .env.local 檔案提交到 git。

用法範例

伺服器端變數只能在公開 RequestEvent 物件的伺服器端 API 中存取，例如 routeLoader$()、routeAction$()、server$() 和端點處理程序，例如 onGet、onPost、onRequest 等。

src/routes/index.tsx

import {
  routeLoader$,
  routeAction$,
  server$,
  type RequestEvent,
} from '@builder.io/qwik-city';
 
export const onGet = (requestEvent: RequestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
};
 
export const onPost = (requestEvent: RequestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
};
 
export const useAction = routeAction$(async (_, requestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
});
 
export const useLoader = routeLoader$(async (requestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
});
 
export const serverFunction = server$(function () {
  // `this` is the `RequestEvent` object
  console.log(this.env.get('DB_PRIVATE_KEY'));
});

在伺服器完整架構中的用法（範例：Express）

若要在伺服器完整架構中存取 .env 變數，您需要使用單例設計模式，在插件中初始化資料庫，並在需要時使用 getDB 存取它。

src/util/db.ts

let _db!: AppDatabase;
 
export function getDB() {
  // eslint-disable-next-line
  if (!_db) {
    throw new Error('DB not set');
  }
  return _db;
}
 
export async function initializeDbIfNeeded(factory: () => Promise<AppDatabase>) {
  // eslint-disable-next-line
  if (!_db) {
    _db = await factory();
  }
}

src/routes/[email 保護]

export const onRequest: RequestHandler = async ({ env }) => {
  const url = env.get('PRIVATE_LIBSQL_DB_URL')!;
  const authToken = env.get('PRIVATE_LIBSQL_DB_API_TOKEN')!;
  await initializeDbIfNeeded(initLibSql(url, authToken));
};

在整個應用程式生命週期中管理環境變數

在現代應用程式中，環境變數在跨各種環境管理應用程式設定和配置方面發揮著至關重要的作用，而無需將敏感數據硬編碼到原始碼中。

Qwik City 轉接器使用以下內容

Azure、Cloud Run、Netlify Edge、Node Server 使用 ORIGIN 或 URL
Cloudflare Pages 使用 CF_PAGES_URL 或 ORIGIN
Vercel 使用 VERCEL_URL

注意：這不是有關環境變數的完整指南，也不涵蓋所有第三方託管情況。它旨在提供可以應用於各種環境的見解。

觀看此影片以獲取詳細說明：https://youtu.be/NPf39RWc8LM

貢獻者

感謝所有幫助改進此文檔的貢獻者！