处理 process.env | Quasar Framework

Quasar CLI with Vite - @quasar/app-vite

处理 process.env

使用 process.env 可以帮助您：

根据 Quasar 模式 (SPA/PWA/Cordova/Electron) 区分运行时的程序
根据开发或生产环境，区分运行时的程序
在构建时根据终端中的环境变量添加标志

Quasar CLI 提供的环境变量

`process.env.<name>`	类型	说明
`DEV`	Boolean	代码运行在开发环境下
`PROD`	Boolean	代码运行在生产环境下
`DEBUGGING`	Boolean	代码运行在开发环境下，或者带 `--debug` 参数的生产模式下
`CLIENT`	Boolean	代码运行在客户端（而不是服务端）
`SERVER`	Boolean	代码运行在服务端（而不是客户端）
`MODE`	String	Quasar 开发模式 (`spa`, `pwa`, …)
`NODE_ENV`	String	有两种取值：`production` 或 `development`
`TARGET`	String	Cordova/Capacitor 模式下为 `ios` 或 `android`，BEX 模式下为 `chrome` 或 `firefox`

示例

if (process.env.DEV) {
  console.log(`I'm on a development build`);
}

// process.env. MODE 来自 "quasar dev/build -m <mode>" 命令中的 <mode> 参数，默认为 spa
if (process.env.MODE === "electron") {
  import("@electron/remote").then(({ BrowserWindow }) => {
    const win = BrowserWindow.getFocusedWindow();

    if (win.isMaximized()) {
      win.unmaximize();
    } else {
      win.maximize();
    }
  });
}

剥离代码

当构建您的网站/应用时，会根据 proces.env 判断 if () 分支。如果表达式为 false，则该分支中的代码会被删除，不会进入到最后的构建产物中去。示例：

if (process.env.DEV) {
  console.log("dev");
} else {
  console.log("build");
}

// 运行 "quasar dev" 会构建出：
console.log("dev");
// 运行 "quasar build" 会构建出：
console.log("build");

注意上面提到的 if 在计算过后，编译时也完全被去掉了，减少构建包的体积。

基于 process.env 的导入

您可以将上一节中学习的内容与动态导入结合起来：

if (process.env.MODE === "electron") {
  import("my-fancy-npm-package").then((package) => {
    // 注意下面的 "default"，您可以通过它来访问 npm 包导出的内容
    package.default.doSomething();
  });
}

添加变量到 process.env

您可以通过 /quasar.config 文件添加自定义的变量到 process.env 中。

了解不同类型的环境变量很重要：

/quasar.config 中定义的来自终端中的变量。
传入您的 UI 代码中的环境变量。

// 访问终端中的变量
console.log(process.env);

export default defineConfig((ctx) => {
  return {
    // ...

    build: {
      // 传入到 UI 代码中的环境变量
      env: {
        API: ctx.dev ? "https://dev.api.com" : "https://prod.api.com",
      },
    },
  };
});

然后，在您的网站/应用中，您可以访问 process .env .API，它会指向上述设置的两个链接中的一个，到底是哪个取决于时开发环境还是生产环境。

您甚至可以将其与 quasar dev/build 命令中的变量的值结合在一起：

# 我们先在终端中设置一个变量
$ MY_API=api.com quasar build

// 然后我们可以将其运用在 /quasar.config 中：
build: {
  env: {
    API: ctx.dev ? "https://dev." + process.env.MY_API : "https://prod." + process.env.MY_API;
  }
}

env dotfiles 支持

关于 env dotfiles 支持的更多说明。以下文件会被自动检测和使用（顺序很重要）：

.env                                # 所有情况下都会加载
.env.local                          # 所有情况下都会加载，被 git 忽略
.env.[dev|prod]                     # 仅在开发或生产模式下加载
.env.local.[dev|prod]               # 仅在开发或生产模式下加载，被 git 忽略
.env.[quasarMode]                   # 仅在特定 Quasar CLI 模式下加载
.env.local.[quasarMode]             # 仅在特定 Quasar CLI 模式下加载，被 git 忽略
.env.[dev|prod].[quasarMode]        # 仅在特定 Quasar CLI 模式和开发/生产模式下加载
.env.local.[dev|prod].[quasarMode]  # 仅在特定 Quasar CLI 模式和开发/生产模式下加载，被 git 忽略

…其中"被 git 忽略"假设项目是在此功能发布后创建的，否则请手动将 .env.local* 添加到 /.gitignore 文件中。

您还可以配置上述文件从不同的目录加载，或者向列表中添加更多文件：

build: {
  /**
   * Quasar CLI 查找 .env* 文件的目录。
   * 可以是绝对路径或相对于项目根目录的路径。
   *
   * @default 项目根目录
   */
  envFolder?: string;

  /**
   * 需要额外加载的 .env* 文件。
   * 每个条目可以是绝对路径或相对于 quasar.config > build > envFolder 的路径。
   *
   * @example ['.env.somefile', '../.env.someotherfile']
   */
  envFiles?: string[];

  /**
   * 过滤通过 env 文件暴露给客户端的环境变量。
   * 不包括直接赋值给 quasar.config > build > env 的定义。
   *
   * 需要 @quasar/app-vite v2.0.3+
   */
  envFilter?:
    (env: { [index: string]: string | boolean | undefined | null })
      => { [index: string]: string | boolean | undefined | null };
}

您可以使用 build > envFilter 过滤不需要的键，甚至修改键的值：

build: {
  // @quasar/app-vite v2.0.3+
  envFilter (originalEnv) {
    const newEnv = {}
    for (const key in originalEnv) {
      if (/* ...决定是否包含... */) {
        newEnv[ key ] = originalEnv[ key ]
      }
    }

    // 记得返回处理后的 env
    return newEnv
  }
}

故障排除

如果您错误地访问变量或者配置不正确，可能会在浏览器控制台中收到 process is not defined 的错误提示。

错误的使用

build: {
  env: {
    FOO: 'hello',
  }
}

const { FOO } = process.env; // ❌ 它不允许解构或类似操作
process.env.FOO; // ✅ 它只能替换直接使用的方式，如此

function getEnv(name) {
  return process.env[name]; // ❌ 它无法分析动态使用情况
}

console.log(process); // ❌
console.log(process.env); // ❌
// 如果您想查看可用的环境变量列表，
// 您可以在 `quasar.config` 中的 “build > env” 内部记录您要传递的对象。

console.log(process.env.FOO); // ✅
console.log(process.env.foo); // ❌ 大小写敏感
console.log(process.env.F0O); // ❌ 变量名存在拼写错误（中间o应为0）

配置错误

手动定义

build: {
  env: {
    FOO: 'hello',
  }
}

console.log(process.env.FOO); // ✅
console.log(process.env.BAR); // ❌ 它未在 `build > env` 中定义

env dotfiles

# 顺序很重要！
.env                                # 所有情况下都会加载
.env.local                          # 所有情况下都会加载，被 git 忽略
.env.[dev|prod]                     # 仅在开发或生产模式下加载
.env.local.[dev|prod]               # 仅在开发或生产模式下加载，被 git 忽略
.env.[quasarMode]                   # 仅在特定 Quasar CLI 模式下加载
.env.local.[quasarMode]             # 仅在特定 Quasar CLI 模式下加载，被 git 忽略
.env.[dev|prod].[quasarMode]        # 仅在特定 Quasar CLI 模式和开发/生产模式下加载
.env.local.[dev|prod].[quasarMode]  # 仅在特定 Quasar CLI 模式和开发/生产模式下加载，被 git 忽略

如果 /.env 文件不存在或文件名存在拼写错误：

console.log(process.env.FOO); // ❌ `.env` 文件未加载，此操作将失败

如果 /.env 文件以正确的名称存在，并且具有以下内容：

FOO=hello

console.log(process.env.FOO); // ✅ 它已从 `.env` 文件中正确加载
console.log(process.env.BAR); // ❌ 它未在 `.env` 文件中定义

视频讲解

quasar 入门教程-quasar 处理 env

发现错误？在浏览器中编辑此页

1. Introduction

2. Quasar CLI 提供的环境变量

3. 示例

4. 剥离代码

5. 基于 process.env 的导入

6. 添加变量到 process.env

7. 故障排除

7.1. 错误的使用

7.2. 配置错误

8. 视频讲解