应用环境变量 (Expo)

Kaiwu 应用（apps/ui）基于 Expo 构建。Expo 支持在本地开发阶段加载 .env* 文件，并在打包/构建期间将 EXPO_PUBLIC_* 变量直接内联到 JS bundle 中。

本地配置覆盖（推荐）

为避免将本地专用的配置提交到 Git，请使用本地环境文件：

cd apps/ui
cp .env.local.example .env.local

随后编辑 apps/ui/.env.local 并重启开发服务器（Metro），即可应用新配置重新构建 bundle。

在构建时禁用功能

你可以在构建时通过设置以下变量来禁用特定的 UI 功能：

• EXPO_PUBLIC_KAIWU_BUILD_FEATURES_DENY

示例：

EXPO_PUBLIC_KAIWU_BUILD_FEATURES_DENY=voice,social.friends

该变量是由逗号分隔的功能 ID 列表（例如 voice、social.friends、bugReports、connectedServices、connectedServices.quotas）。

关联服务的构建开关

关联服务也提供了显式的构建期开关：

• EXPO_PUBLIC_KAIWU_FEATURE_CONNECTED_SERVICES__ENABLED（默认值：true）
• EXPO_PUBLIC_KAIWU_FEATURE_CONNECTED_SERVICES_QUOTAS__ENABLED（默认值：false）

示例：

# Completely disable Connected Services in the UI bundle
EXPO_PUBLIC_KAIWU_FEATURE_CONNECTED_SERVICES__ENABLED=0

# Enable Connected Services quota UI surfaces
EXPO_PUBLIC_KAIWU_FEATURE_CONNECTED_SERVICES_QUOTAS__ENABLED=1

覆盖 Socket 传输方式（极少使用）

默认情况下，应用遵循 Socket.IO / Engine.IO 的默认机制（先使用 HTTP 长轮询，可行时再升级为 WebSocket）。对于企业代理和受限网络环境，这是兼容性最好的方案。

如果你需要强制仅使用 WebSocket（例如：在没有粘性会话的多服务器集群部署中，你希望快速失败而不是回退到长轮询），请设置：

• EXPO_PUBLIC_KAIWU_SOCKET_FORCE_WEBSOCKET=1

安全说明（重要）

只有 EXPO_PUBLIC_* 变量会被内联到应用 bundle 中。请务必将所有 EXPO_PUBLIC_* 的值视为公开数据（切勿在此存储任何机密敏感信息）。

EAS 构建（云端）

EAS 构建机不会读取本地的 .env.local。对于云端构建，请通过以下任一方式配置这些变量：

• 位于 apps/ui/eas.json 内的 build.⟦K6⟧.env 下，或者
• 在 Expo 项目的 EAS 环境变量界面中配置（并确保构建 Profile 设置了匹配的 "environment"）。

如果你正在使用 hstack 栈，并在栈的环境文件中配置了非公开的 Expo 配置环境变量（例如 EXPO_APP_*、EXPO_EAS_PROJECT_ID、EXPO_UPDATES_URL），可以通过以下命令将它们同步到 EAS：

hstack stack eas <stack> env:sync --environment production

参见：Mobile (iOS)（各栈的 EAS 构建）。