环境信息

environment 模块提供当前小程序实例的静态环境快照，包括运行模式、小黑盒 App 版本、canonical 小程序身份、操作系统和 SDK 版本。该能力无需在 heybox.permissions 中声明，也不会触发用户授权。

推荐用法

优先使用异步方法。SDK 尚未完成握手时，getInfo() 会自动等待：

import { environment } from '@heybox/hb-sdk'

const info = await environment.getInfo()

console.log(info.runtime.mode)
console.log(info.host.appVersion)
console.log(info.miniProgram.id, info.miniProgram.version)
console.log(info.operatingSystem.name, info.operatingSystem.version)
console.log(info.sdk.version)

返回对象采用固定结构并深度冻结：

interface MiniProgramEnvironmentInfo {
  readonly runtime: {
    readonly mode: 'production' | 'preview' | 'development' | 'unknown'
  }
  readonly host: {
    readonly appVersion: string | null
  }
  readonly miniProgram: {
    readonly id: string | null
    readonly version: string | null
  }
  readonly operatingSystem: {
    readonly name: 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown'
    readonly version: string | null
  }
  readonly sdk: {
    readonly version: string
  }
}

同步读取

只有已经确认 SDK 为 ready 时才能调用 getInfoSync()。SDK 会在派发 ready 状态前缓存环境快照，因此可以在握手状态订阅中同步读取：

import { environment, onHandshakeStateChange } from '@heybox/hb-sdk'

const unsubscribe = onHandshakeStateChange(state => {
  if (state.status !== 'ready') return

  const info = environment.getInfoSync()
  console.log(info.operatingSystem.name)
})

握手完成前调用会抛出 HbMiniProgramSDKError，错误码为 ENVIRONMENT_NOT_READY。通常不需要自行等待握手；不要求同步执行的代码直接使用 await environment.getInfo()。

字段语义

字段	语义
`runtime.mode`	当前实例的粗粒度运行模式。正式发布为 `production`，版本预览为 `preview`，本地或 Dev Session 为 `development`。
`host.appVersion`	当前小黑盒 App 版本。它是 Host 提供的不透明字符串。
`miniProgram.id`	平台确认的 canonical `mini_program_id`，不返回数字 ID、用户 ID 或其他旧 ID。
`miniProgram.version`	当前加载的小程序版本，是不透明字符串。
`operatingSystem.name`	Host 明确提供的标准系统枚举，不从小程序 iframe 的 UA 推断。
`operatingSystem.version`	Host 明确提供的系统版本；当前 Host 未提供时为 `null`。
`sdk.version`	当前页面实际运行的 `@heybox/hb-sdk` 版本，遵循 npm SemVer。

除 sdk.version 外，其他版本字段均不承诺 SemVer 或大小比较语义。需要判断某项能力是否可用时，应依据能力调用结果进行降级，不要仅比较 App 或系统版本。

缺失与兼容

旧 Host、匿名本地调试或未提供某个字段的 Host 仍会返回完整结构：缺失字符串为 null，未知枚举为 'unknown'。非法 Host 字段只会被逐项降级，不会阻断 SDK 握手。

Browser Mock 在 Runtime 启动时使用当前设备预设作为操作系统名称，不读取开发者电脑的 UA。切换设备预设会保留当前 Runtime 和页面状态；需要重新生成环境快照时，使用调试台的重启操作。

信任边界

环境信息仅用于界面适配、兼容降级、埋点和诊断，不能用于鉴权、权限控制或风控。小程序提交给服务端的任何环境字段都可能被修改；服务端安全判断必须使用自身认证上下文或平台受信数据。

该 API 不提供设备型号、品牌、UA、CPU、内存、设备唯一标识、账号信息或凭据。屏幕和安全区域继续通过 viewport.getWindowInfo() 获取。

环境信息 ​

推荐用法 ​

同步读取 ​

字段语义 ​

缺失与兼容 ​