使用应用配置进行配置

了解 app.json/app.config.js/app.config.ts 文件是什么以及如何动态自定义和使用它们。

应用配置（app.json、app.config.js、app.config.ts）用于配置 Expo 预建 生成、项目如何在 Expo 中加载以及 OTA 更新清单。

¥The app config (app.json, app.config.js, app.config.ts) is used for configuring Expo Prebuild generation, how a project loads in Expo Go, and the OTA update manifest.

它必须位于项目的根目录中，package.json 旁边。这是一个最小的例子：

¥It must be located at the root of your project, next to the package.json. Here is a minimal example:

{
  "name": "My app",
  "slug": "my-app"
}

如果你的 Expo 配置有一个顶层 expo: {} 对象，那么它将代替根对象，并且所有其他键将被忽略。

¥If your Expo config has a top-level expo: {} object, then this will be used in place of the root object and all other keys will be ignored.

属性

¥Properties

应用配置配置许多内容，例如应用名称、图标、启动屏幕、深度链接方案、用于某些服务的 API 密钥等。有关可用属性的完整列表，请参阅 app.json/app.config.js/app.config.ts 参考。

¥The app config configures many things such as app name, icon, splash screen, deep linking scheme, API keys to use for some services and so on. For a complete list of available properties, see app.json/app.config.js/app.config.ts reference.

你使用 Visual Studio 代码吗？如果是这样，我们建议你安装 Expo 工具 扩展以自动补齐 app.json 文件中的属性。

读取应用中的配置值

¥Reading configuration values in your app

应用配置中的大多数配置都可以在运行时通过 JavaScript 代码使用 Constants.expoConfig 进行访问。你不应在应用配置中包含任何敏感信息（过滤掉的字段有一些例外，如下所述）。

¥Most configuration in the app config is accessible at runtime from your JavaScript code, using Constants.expoConfig. You should not include any sensitive information in the app config (with a few exceptions for fields that are filtered out, as outlined below).

你可以通过运行 npx expo config --type public 来验证哪些配置将嵌入到你的构建/更新中并在运行时可用。

¥You can verify which configuration will be embedded in your builds/updates and available at runtime by running npx expo config --type public.

You should also avoid importing app.json or app.config.js directly in your JavaScript code, because this will import the entire file rather than a processed version of it. Instead, use Constants.expoConfig to access the configuration.

Extending configuration

Library authors can extend the app config by using Expo Config plugins.

info 配置插件主要用于配置 npx expo prebuild 命令。

¥info Config plugins are mostly used to configure the npx expo prebuild command.

动态配置

¥Dynamic configuration

为了实现更多自定义，你可以使用 JavaScript (app.config.js) 或 TypeScript (app.config.ts)。这些配置具有以下属性：

¥For more customization, you can use the JavaScript (app.config.js) or TypeScript (app.config.ts). These configs have the following properties:

• 注释、变量和单引号。

  ¥Comments, variables, and single quotes.

• 不支持 ESM 导入语法（import 关键字），除非使用 使用 TypeScript 和 ts-node。可以使用 require() 导入与你当前 Node.js 版本兼容的 JS 文件。

  ¥ESM import syntax (the import keyword) is not supported, except when using TypeScript with ts-node. JS files that are compatible with your current version of Node.js can be imported with require().

• TypeScript 支持空值合并和可选链式调用。

  ¥TypeScript support with nullish coalescing and optional chaining.

• Metro 打包器每次重新加载时都会更新。

  ¥Updated whenever Metro bundler reloads.

• 向你的应用提供环境信息。

  ¥Provide environment information to your app.

• 不支持 Promises。

  ¥Does not support Promises.

例如，你可以导出一个对象来定义你的自定义配置：

¥For example, you can export an object to define your custom config:

const myValue = 'My App';

module.exports = {
  name: myValue,
  version: process.env.MY_CUSTOM_PROJECT_VERSION || '1.0.0',
  // All values in extra will be passed to your app.
  extra: {
    fact: 'kittens are cool',
  },
};

"extra" 键允许将任意配置数据传递给你的应用。此键的值使用 expo-constants 访问：

¥The "extra" key allows passing arbitrary configuration data to your app. The value of this key is accessed using expo-constants:

import Constants from 'expo-constants';

Constants.expoConfig.extra.fact === 'kittens are cool';

你可以通过导出返回对象的函数来访问和修改传入的配置值。如果你的项目也包含 app.json 文件，这将非常有用。默认情况下，Expo CLI 会首先读取 app.json 文件，并将规范化的结果发送到 app.config.js 文件。

¥You can access and modify incoming config values by exporting a function that returns an object. This is useful if your project also has an app.json. By default, Expo CLI will read the app.json first and send the normalized results to the app.config.js.

例如，你的 app.json 文件可能如下所示：

¥For example, your app.json could look like this:

{
  "name": "My App"
}

在你的 app.config.js 中，导出函数的参数会提供该配置：

¥And in your app.config.js, you are provided with that configuration in the arguments to the exported function:

module.exports = ({ config }) => {
  console.log(config.name); // prints 'My App'
  return {
    ...config,
  };
};

根据环境切换配置

¥Switching configuration based on the environment

在开发、预发布和生产环境中，通常会有一些不同的配置，或者完全替换配置以创建白标应用。为此，你可以将 app.config.js 与环境变量结合使用。

¥It's common to have some different configuration in development, staging, and production environments, or to swap out configuration entirely to white label an app. To accomplish this, you can use app.config.js along with environment variables.

module.exports = () => {
  if (process.env.MY_ENVIRONMENT === 'production') {
    return {
      /* your production config */
    };
  } else {
    return {
      /* your development config */
    };
  }
};

要将此配置与 Expo CLI 命令一起使用，请为特定命令或在 Shell 配置文件中设置环境变量。要为特定命令设置环境变量，请在命令前添加变量和值，如示例所示：

¥To use this configuration with Expo CLI commands, set the environment variable either for specific commands or in your shell profile. To set environment variables for specific commands, prefix the command with the variables and values as shown in the example:

这并非 Expo CLI 独有的功能。在 Windows 上，你可以使用以下命令近似执行上述命令：

¥This is not anything unique to Expo CLI. On Windows you can approximate the above command with:

或者，你可以使用任何其他你熟悉的环境变量机制。

¥Or you can use any other mechanism that you are comfortable with for environment variables.

使用 TypeScript 进行配置：使用 app.config.ts 而不是 app.config.js

¥Using TypeScript for configuration: app.config.ts instead of app.config.js

你可以在 TypeScript 中将自动补齐和文档块与 Expo 配置一起使用。创建一个包含以下内容的 app.config.ts 文件：

¥You can use autocomplete and doc-blocks with an Expo config in TypeScript. Create an app.config.ts with the following contents:

import { ExpoConfig, ConfigContext } from 'expo/config';

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  slug: 'my-app',
  name: 'My App',
});

要将其他 TypeScript 文件导入 app.config.ts 或自定义语言特性，我们建议使用 ts-node。ts-node 还支持在 app.config.ts 导入的任何文件中使用 import 语法。这意味着你可以使用 TypeScript 编写具有完整语言特性的本地 配置插件。

¥To import other TypeScript files into app.config.ts or customize the language features, we recommend using ts-node. ts-node also enables using import syntax in any file imported by app.config.ts. This means you can write local config plugins in TypeScript with full language features.

配置解析规则

¥Configuration resolution rules

有两种不同类型的配置：静态（app.config.json、app.json）和动态（app.config.js、app.config.ts）。静态配置可以使用 CLI 工具自动更新，而动态配置必须由开发者手动更新。

¥There are two different types of configs: static (app.config.json, app.json), and dynamic (app.config.js, app.config.ts). Static configs can be automatically updated with CLI tools, whereas dynamic configs must be manually updated by the developer.

1. 如果 app.config.json 存在，则会读取静态配置（回退到 app.json）。如果不存在静态配置，则默认值将从 package.json 和你的依赖中推断出来。

   ¥The static config is read if app.config.json exists (falls back to app.json). If no static config exists, then default values are inferred from the package.json and your dependencies.

2. 如果 app.config.ts 或 app.config.js 存在，则会读取动态配置。如果两者都存在，则使用 TypeScript 配置。

   ¥The dynamic config is read if either app.config.ts or app.config.js exist. If both exist, then the TypeScript config is used.

3. 如果动态配置返回一个函数，则静态配置将与 ({ config }) => ({}) 一起传递给该函数。此函数可以修改静态配置的值。可以将其视为静态配置的中间件。

   ¥If the dynamic config returns a function, then the static config is passed to the function with ({ config }) => ({}). This function can then mutate the static config values. Think of this like middleware for the static config.

4. 动态配置的返回值将用作最终配置。它不能包含任何 Promise。

   ¥The return value from the dynamic config is used as the final config. It cannot have any promises.

5. Expo 生态系统中的任何工具使用配置之前，配置中的所有函数都会被评估和序列化。托管时，配置必须是 JSON 清单。

   ¥All functions in the config are evaluated and serialized before any tool in the Expo ecosystem uses it. The config must be a JSON manifest when it is hosted.

6. 如果最终配置对象包含顶层 expo: {} 对象，则该对象将代替根对象，并且所有其他键都将被忽略。

   ¥If the final config object has a top-level expo: {} object, then this will be used in place of the root object and all other keys will be ignored.

运行 npx expo config 将显示解析后将在 Expo CLI 中使用的最终配置。

¥Running npx expo config will display the final configuration that will be used in Expo CLI after resolution has occurred.