使用应用配置进行配置

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

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

Dynamic configuration

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 syntax (the import keyword) is not supported, except when using TypeScript with tsx. JS files that are compatible with your current version of Node.js can be imported with require().
• TypeScript support with nullish coalescing and optional chaining.
• Updated whenever Metro bundler reloads.
• Provide environment information to your app.
• 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',
  },
};

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';

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.

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

{
  "name": "My App"
}

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

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 */
    };
  }
};

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:

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

¥To import other TypeScript files into app.config.ts or customize the language features, we recommend using tsx. tsx 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.