使用应用配置进行配置

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

应用配置（app.json、app.config.js、app.config.ts）用于配置 Expo Prebuild 的生成、项目在 Expo Go 中的加载方式，以及 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 Code 吗？如果是，我们建议你安装 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:

• 注释、变量和单引号。
• ESM 导入语法（import 关键字）不被支持，除非使用 TypeScript 与 tsx。与当前 Node.js 版本兼容的 JS 文件可以通过 require() 导入。
• TypeScript 支持空值合并运算符和可选链操作符。
• 每当 Metro 打包器重新加载时更新。
• 向你的应用提供环境信息。
• 不支持 Promise。

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

🌐 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 或自定义语言功能，我们建议使用 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 和你的依赖推断默认值。
2. 如果存在 app.config.ts 或 app.config.js，将会读取动态配置。如果两者都存在，则使用 TypeScript 配置。
3. 如果动态配置返回一个函数，那么静态配置将作为参数与 ({ config }) => ({}) 一起传递给该函数。然后，该函数可以修改静态配置的值。可以把它想象成静态配置的中间件。
4. 动态配置的返回值将作为最终配置使用。它不能包含任何 Promise。
5. 在 Expo 生态系统中的任何工具使用配置之前，配置中的所有函数都会被评估并序列化。配置在托管时必须是 JSON 清单。
6. 如果最终配置对象包含顶层 expo: {} 对象，那么将使用它来代替根对象，其他所有键将被忽略。

运行 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.