使用应用配置进行配置

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

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

应用配置（app.json、app.config.js、app.config.ts）用于配置 Expo Prebuild 的生成、项目在 Expo Go 中的加载方式，以及 OTA 更新清单。

它必须位于项目根目录，紧挨着 package.json。下面是一个最小示例：

{
  "name": "我的应用",
  "slug": "my-app"
}

如果你的 Expo 配置包含顶层的 expo: {} 对象，那么它将被用作根对象，其它所有键都会被忽略。

属性

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

你使用 Visual Studio Code 吗？如果是，我们建议安装 Expo Tools 扩展，以便在 app.json 文件中自动补全属性。

在应用中读取配置值

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

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

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

扩展配置

库的作者可以通过使用 Expo Config plugins 来扩展 app 配置。

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

动态配置

为了进行更多自定义，你可以使用 JavaScript（app.config.js）或 TypeScript（app.config.ts）。这些配置具有以下特性：

• 支持注释、变量和单引号。
• 不支持 ESM import 语法（import 关键字），但使用 TypeScript with tsx 时除外。与当前 Node.js 版本兼容的 JS 文件可以使用 require() 导入。
• 支持带有 nullish coalescing 和可选链的 TypeScript。
• 当 Metro bundler 重新加载时会更新。
• 向你的应用提供环境信息。
• 不支持 Promises。

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

const myValue = '我的应用';

module.exports = {
  name: myValue,
  version: process.env.MY_CUSTOM_PROJECT_VERSION || '1.0.0',
  // extra 中的所有值都会传递给你的应用。
  extra: {
    fact: '小猫很可爱',
  },
};

"extra" 键允许向你的应用传递任意配置数据。该键的值可通过 expo-constants 访问：

import Constants from 'expo-constants';

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

你可以通过导出一个返回对象的函数来访问和修改传入的配置值。如果你的项目中也有 app.json，这会很有用。默认情况下，Expo CLI 会先读取 app.json，然后将规范化后的结果传递给 app.config.js。

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

{
  "name": "我的应用"
}

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

module.exports = ({ config }) => {
  console.log(config.name); // 打印 '我的应用'
  return {
    ...config,
  };
};

根据环境切换配置

在开发、预发布和生产环境中拥有不同的配置很常见，或者完全替换配置以进行白标应用定制。为实现这一点，你可以结合环境变量使用 app.config.js。

module.exports = () => {
  if (process.env.MY_ENVIRONMENT === 'production') {
    return {
      /* 你的生产环境配置 */
    };
  } else {
    return {
      /* 你的开发环境配置 */
    };
  }
};

要在 Expo CLI 命令中使用此配置，请为特定命令或在你的 shell 配置文件中设置环境变量。要为特定命令设置环境变量，请像示例中所示，在命令前加上变量和对应值：

这并不是 Expo CLI 独有的特性。在 Windows 上，你可以用以下方式近似实现上述命令：

或者你也可以使用任何你熟悉的其它环境变量处理方式。

使用 TypeScript 进行配置：使用 app.config.ts 替代 app.config.js

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

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

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  slug: 'my-app',
  name: '我的应用',
});

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

配置解析规则

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

1. 如果 app.config.json 存在，则读取静态配置（否则回退到 app.json）。如果不存在静态配置，则会从 package.json 和你的依赖项中推断默认值。
2. 如果 app.config.ts 或 app.config.js 任一存在，则读取动态配置。如果两者都存在，则使用 TypeScript 配置。
3. 如果动态配置返回一个函数，则静态配置会以 ({ config }) => ({}) 的形式传递给该函数。然后这个函数可以修改静态配置值。可以把这看作静态配置的中间件。
4. 动态配置的返回值会作为最终配置。它不能包含任何 promises。
5. 在 Expo 生态系统中的任何工具使用配置之前，配置中的所有函数都会被求值并序列化。配置在托管时必须是 JSON 清单。
6. 如果最终配置对象包含顶层的 expo: {} 对象，那么它将被用作根对象，其它所有键都会被忽略。

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