使用应用配置进行配置

了解 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.

你还应该避免直接在 JavaScript 代码中导入 app.json 或 app.config.js，因为这将导入整个文件而不是其处理后的版本。相反，请使用 Constants.expoConfig 访问配置。

扩展配置

¥Extending configuration

库作者可以使用 Expo 配置插件 来扩展应用配置。

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

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

动态配置

¥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 关键字），除非使用 带有 ts-node 的 TypeScript。可以使用 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.

• 不支持 promise。

  ¥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.