处理 process.env | Quasar Framework

Quasar CLI with Webpack - @quasar/app-webpack

处理 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'，如果没指定 -m 参数的话）

if (process.env.MODE === "electron") {
  const { BrowserWindow } = require("@electron/remote");
  const win = BrowserWindow.getFocusedWindow();

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

剥离代码

当构建您的网站/应用时，会根据 process.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]                     # 仅在 dev 或 prod 模式下加载
.env.local.[dev|prod]               # 仅在 dev 或 prod 模式下加载，被 git 忽略
.env.[quasarMode]                   # 仅在特定的 Quasar CLI 模式下加载
.env.local.[quasarMode]             # 仅在特定的 Quasar CLI 模式下加载，被 git 忽略
.env.[dev|prod].[quasarMode]        # 仅在特定的 Quasar CLI 模式和 dev|prod 下加载
.env.local.[dev|prod].[quasarMode]  # 仅在特定的 Quasar CLI 模式和 dev|prod 下加载，被 git 忽略

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

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

build: {
  /**
   * Folder where Quasar CLI should look for .env* files.
   * Can be an absolute path or a relative path to project root directory.
   *
   * @default project root directory
   */
  envFolder?: string;

  /**
   * Additional .env* files to be loaded.
   * Each entry can be an absolute path or a relative path to quasar.config > build > envFolder.
   *
   * @example ['.env.somefile', '../.env.someotherfile']
   */
  envFiles?: string[];

  /**
   * Filter the env variables that are exposed to the client
   * through the env files. This does not account also for the definitions
   * assigned directly to quasar.config > build > env prop.
   *
   * Requires @quasar/app-webpack v4.0.3+
   */
  envFilter?:
    (env: { [index: string]: string | boolean | undefined | null })
      => { [index: string]: string | boolean | undefined | null };
}

请记住，您可以使用 build > envFilter 来过滤掉不需要的 key，甚至修改 key 的值：

build: {
  // @quasar/app-webpack v4.0.3+
  envFilter (originalEnv) {
    const newEnv = {}
    for (const key in originalEnv) {
      if (/* ...decide if it goes in or not... */) {
        newEnv[ key ] = originalEnv[ key ]
      }
    }

    // remember to return your processed env
    return newEnv
  }
}

故障排除

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

错误的使用

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]                     # 仅在 dev 或 prod 模式下加载
.env.local.[dev|prod]               # 仅在 dev 或 prod 模式下加载，被 git 忽略
.env.[quasarMode]                   # 仅在特定的 Quasar CLI 模式下加载
.env.local.[quasarMode]             # 仅在特定的 Quasar CLI 模式下加载，被 git 忽略
.env.[dev|prod].[quasarMode]        # 仅在特定的 Quasar CLI 模式和 dev|prod 下加载
.env.local.[dev|prod].[quasarMode]  # 仅在特定的 Quasar CLI 模式和 dev|prod 下加载，被 git 忽略

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

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

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

FOO=hello

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

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

1. Introduction

2. Quasar CLI 提供的环境变量

3. 示例

4. 剥离代码

5. 基于 process.env 的导入

6. 添加变量到 process.env

7. 故障排除

7.1. 错误的使用

7.2. 配置错误