# @bi-nova/core 中文文档

规范地址：https://npmcn.com/package/%40bi-nova/core/

版本：2\.0\.0
npm 元数据更新时间：2026-11-03T09:46:09.920Z
中文译文更新时间：2026-11-08T01:22:38.971Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bi-nova/core
原文对照：https://npmcn.com/package/%40bi-nova/core/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：63.8 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@leyaoyao/qt-hook-h5 1\.0\.5，@leyaoyao/qt-hook-alipay 1\.0\.3，@leyaoyao/qt-hook-native 1\.0\.4，@leyaoyao/qt-hook-wechat 1\.0\.3
- 首次发布：2026-05-16T04:25:30.305Z
- 最新版本发布：2026-11-03T09:46:09.531Z
- 近 30 天下载量：2744（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

BI Nova SDK 核心软件

## 安装

```sh
npm install @bi-nova/core
```

也可以使用：`pnpm add @bi-nova/core`、`yarn add @bi-nova/core`、`bun add @bi-nova/core`

## README

# @bi-nova/core

NovaSDK 核心包，提供跨平台适配器和插件系统。

支持环境：H5（浏览器）、微信小程序、支付宝小程序。

## 安装

::: code-group

```bash
pnpm add @bi-nova/core
```

```bash
npm install @bi-nova/core
```

:::

## 快速开始

> ⚠️ **重要提示**：
> 
> -   **微信小程序/支付宝小程序**：必须设置 `autoEnv: true` 或手动指定适配器，否则网络请求、存储等功能将无法正常使用
> -   **H5 应用**：可省略 `autoEnv`（默认使用 WebAdapter）

### 微信小程序

```ts
import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // ⚠️ 小程序环境必须开启，使用 wx.request / wx.getStorageSync 等原生 API
})
```

或者手动指定适配器：

```ts
import { createNova, WechatAdapter } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  adapter: new WechatAdapter(),
})
```

### 支付宝小程序

```ts
import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // ⚠️ 小程序环境必须开启，使用 my.request / my.getStorageSync 等原生 API
})
```

### H5 应用（浏览器）

```ts
import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  // autoEnv 可省略，默认使用 WebAdapter（fetch / localStorage）
})
```

## 核心概念

### 适配器（Adapter）

适配器抹平不同平台的 API 差异，所有适配器均实现 `AdapterInterface`：

| 方法 | 说明 |
| --- | --- |
| `request(url, options)` | 发起网络请求 |
| `storage.get(key)` | 读取本地存储 |
| `storage.set(key, value)` | 写入本地存储 |
| `navigate(url)` | 页面跳转 |
| `getEnv()` | 返回当前环境标识 |

内置适配器：

| 适配器 | 环境 | 底层实现 |
| --- | --- | --- |
| `WebAdapter` | H5 / 浏览器 | `fetch` / `localStorage` / `location.href` |
| `WechatAdapter` | 微信小程序 | `wx.request` / `wx.getStorageSync` / `wx.navigateTo` |
| `AlipayAdapter` | 支付宝小程序 | `my.request` / `my.getStorageSync` / `my.navigateTo` |

### 插件系统

通过 `nova.use(plugin)` 注册插件，插件需满足 `Plugin` 接口：

```ts
interface Plugin {
  name: string
  install(sdk: NovaSDK): void
}
```

示例：

```ts
import { createServices } from '@bi-nova/services'

nova.use(createServices({ env: 'sit', debug: true }))
```

同名插件仅安装一次，重复调用 `use()` 会跳过并打印警告。

## API

### `createNova(config)`

工厂函数，创建 `NovaSDK` 实例。

**参数：`NovaConfig`**

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `appId` | `string` | 否 | `bi_nova` | 宿主应用及埋点项目标识，同时用于生成当前 SDK 埋点实例的 namespace |
| `autoEnv` | `boolean` | 否 | `false` | 自动检测环境并选择适配器。**小程序环境必须设为 `true`**，否则网络请求、存储等功能将无法使用 |
| `adapter` | `AdapterInterface` | 否 | \- | 手动指定适配器（优先级高于 `autoEnv`）。如 `new WechatAdapter()` |
| `tracking` | `AdvertTrackerConfig` | 否 | 内置 QT 配置 | SDK 初始化时自动创建埋点实例；appId 统一使用外层 `NovaConfig.appId`（未传时为 `bi_nova`），可配置 `url` 或设置 `enabled: false` 关闭 |

埋点在第一条事件到达时懒初始化，默认沿用 `_Lyy_Bury_Point:${appId}` storage key。 同一 appId 存在多个 SDK 实例时，可传 `tracking.instanceKey`，或配置 `tracking: { isolateByNamespace: true }` 使用 `advert-plugin:${appId}:${instanceKey || 'default'}` 隔离会话；显式传入 `tracking.namespace` 的优先级最高。

### userId 与匿名访客身份

埋点始终使用 qt-hook payload 顶层的 `userId` 字段，不增加 `biVisitorId` 等扩展字段。

-   `tracking.getUserId` 仅用于同步读取宿主已经缓存的真实用户 ID，不能在其中发起异步登录请求。
-   如果初始化时没有真实 ID，SDK 默认在当前 namespace 生成一次 `anon_v1_<唯一值>`，并写入持久化 storage：微信/支付宝使用 `setStorageSync`，H5 使用 `localStorage`，不会使用 `sessionStorage`。
-   登录接口异步返回后调用 `await nova.tracking.setUserId(loginResult.userId)`，后续事件会覆盖为真实 ID。
-   退出登录调用 `await nova.tracking.clearUserId()`，恢复同一 namespace 的匿名 ID。
-   匿名 ID 只保存在 SDK 自己的 `__BI_NOVA_USER_ID__:<namespace>` key 中，不扫描或读取其他 `_Lyy_Bury_Point*` key，也不会把真实账号写入该匿名 key。

示例：

```ts
const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true,
  tracking: {
    getUserId: () => app.globalData.userId || undefined,
  },
})

const loginResult = await login()
app.globalData.userId = loginResult.userId
await nova.tracking.setUserId(loginResult.userId)
```

React Native 需要在创建 SDK 前注册 Native 端实现：

```ts
import '@bi-nova/core/native'
```

**返回值：** `NovaSDK` 实例

**适配器选择逻辑：**

1.  若传入 `adapter`，直接使用
2.  若 `autoEnv: true`，调用 `detectEnv()` 自动选择
3.  **否则默认使用 `WebAdapter`** ⚠️ 小程序环境必须设置 `autoEnv: true`，否则功能异常

### `NovaSDK` 实例方法

| 方法 | 签名 | 说明 |
| --- | --- | --- |
| `use` | `(plugin: Plugin) => this` | 注册插件 |
| `request` | `(url: string, options?: any) => Promise<any>` | 发起网络请求（代理适配器） |
| `getStorage` | `(key: string) => any` | 读取本地存储 |
| `setStorage` | `(key: string, value: any) => void` | 写入本地存储 |
| `navigate` | `(url: string) => void` | 页面跳转 |
| `getEnv` | `() => string` | 获取当前环境标识 |

### `NovaSDK` 实例属性

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `config` | `NovaConfig` | 初始化配置 |
| `tracking` | `AdvertTracker` | 当前 SDK 实例的埋点实例；组件生命周期事件会复用该实例 |
| `ui` | `UIPlugin` | UI 组件插件入口 |

`nova.tracking` 用户身份方法：

```ts
await nova.tracking.setUserId(loginResult.userId) // 覆盖 anon_v1_...
await nova.tracking.clearUserId()                 // 恢复持久化匿名 ID
const userId = nova.tracking.getUserId()
```

### `detectEnv()`

检测当前运行环境。

```ts
import { detectEnv } from '@bi-nova/core'

const env = detectEnv() // 'web' | 'wechat' | 'alipay' | 'unknown'
```

**检测优先级：** `wechat` > `alipay` > `web` > `unknown`

## UMD 使用

通过 `<script>` 标签引入 UMD 产物后，所有导出挂载在 `window.BiNova` 上：

```html
<script src="bi-nova.umd.js"></script>
<script>
  const { createNova } = window.BiNova
  const nova = createNova({ appId: 'xxx', autoEnv: true })
</script>
```

UMD 全局类型声明可通过 `@bi-nova/core/global` 导入：

```ts
/// <reference types="@bi-nova/core/global" />
```

## 类型导出

```ts
import type {
  AdapterInterface,
  NovaConfig,
  Plugin,
} from '@bi-nova/core'

import type { ComponentBinding, ComponentHandle } from '@bi-nova/core'
```

## 故障排查

### Q: 小程序中报错 "fetch is not defined" 或 "localStorage is not defined"？

**原因：** 未设置 `autoEnv: true`，SDK 默认使用 WebAdapter（依赖 `fetch`、`localStorage` 等 Web API），而小程序环境不支持这些 API。

**解决方案：**

```ts
// 方式一：开启自动环境检测（推荐）
const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // 自动选择 WechatAdapter 或 AlipayAdapter
})

// 方式二：手动指定适配器
import { WechatAdapter } from '@bi-nova/core'
const nova = createNova({
  appId: 'your-app-id',
  adapter: new WechatAdapter(),
})
```

### Q: 小程序中网络请求、存储功能不工作？

**原因：** 同上，使用了错误的适配器。

**解决方案：** 设置 `autoEnv: true` 或手动指定对应平台的适配器。

### Q: 如何确认当前使用的适配器？

**方法：** 调用 `nova.getEnv()` 查看当前环境：

```ts
console.log(nova.getEnv()) // 'web' | 'wechat' | 'alipay'
```

### Q: 跨端开发（Taro/uniapp）如何配置？

**推荐配置：** 设置 `autoEnv: true`，让 SDK 根据运行环境自动选择适配器：

```ts
const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // H5 用 WebAdapter，小程序用对应适配器
})
```

## 常见问题

### @bi-nova/core 是什么？

BI Nova SDK 核心软件

### 如何安装 @bi-nova/core？

在项目目录运行 npm install @bi-nova/core，或使用 pnpm add / yarn add / bun add。

### @bi-nova/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bi-nova/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bi-nova/core 可以商用吗？

@bi-nova/core 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bi-nova/core 的下载量有多少？

根据 npm 官方下载统计，@bi-nova/core 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,744 次，日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bi-nova/core 还在维护吗？

最新版本 2\.0\.0 发布于 2026/11/03（5 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/05/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。