集成指南

June 18, 2026 · View on GitHub

← 返回首页 | English

以下示例假定您已在 Releases 页面 下载对应版本的二进制包或源码。

C++（动态库 / 静态库 / 源码）

  • 动态库 下载 dynamic_lib_{version} 压缩包：

    • 将 dynamic_lib/include 目录添加到头文件搜索路径；
    • 链接 dynamic_lib/lib 中对应平台的动态库文件。

  • 静态库 下载 static_lib_{version} 压缩包：

    • 将 static_lib/include 目录添加到头文件搜索路径；
    • 链接 static_lib/lib 中对应平台的静态库文件。

  • 源码集成

    • 将仓库下的 /src 目录加入工程源码编译；
    • 将 /include 目录添加到头文件搜索路径。
    • Windows + Visual Studio：请添加编译选项 /Zc:__cplusplus。
    • Android 模式下支持 ANDROID_STL = none。
    • 如需启用 Java / NAPI（Node.js / HarmonyOS ArkTS）支持，以及系统链接库与部分宏定义，请参考 /src/CMakeLists.txt（如果觉得难以理解，建议求助AI提炼）。
    • 当存在 NAPI 环境（Node.js 或 HarmonyOS ArkTS）或需要 Java / C# 调用时，不推荐以「纯 C++ 源码」直接集成，因为需要手动处理初始化和库加载流程；更推荐使用预编译包及对应 wrapper。

C#（Unity / 团结引擎 / .NET）

  • Unity / 团结引擎 完整引擎集成步骤请见 游戏引擎集成指南。

  • .NET

    • 下载对应平台的动态库包 {os}_{arch}_libs_{version}，引入其中动态库；
    • 将 C# wrapper 源码加入工程 —— 可以直接使用仓库下 /wrapper/csharp/src，也可以从 Releases 页面 下载 c#_wrapper_{version} 预打包的源码包。

iOS / Apple 平台（C++ / Objective-C）

从 Releases 页面 下载 ios_libs_{version}。包内包含 BqLog.xcframework，支持多个 Apple 平台（iOS 真机、iOS 模拟器、tvOS、watchOS、visionOS）及多种构建配置（Debug、Release、RelWithDebInfo、MinSizeRel）。

通过 Xcode 集成

  1. 将 BqLog.xcframework 拖入 Xcode 工程；
  2. 在 target 的 General → Frameworks, Libraries, and Embedded Content 中，确保 BqLog.xcframework 设置为 Embed & Sign；
  3. 在源码中包含头文件：
#include "bq_log/bq_log.h"

通过 CMake 集成（适用于基于 CMake 的 iOS 工程）

# 将路径替换为你放置 xcframework 的实际位置
set(BQLOG_XCFRAMEWORK_PATH "${CMAKE_CURRENT_SOURCE_DIR}/path/to/BqLog.xcframework")
find_library(BQLOG_LIB BqLog PATHS ${BQLOG_XCFRAMEWORK_PATH} REQUIRED)

target_link_libraries(${CMAKE_PROJECT_NAME} ${BQLOG_LIB})
target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
    "${BQLOG_XCFRAMEWORK_PATH}/Headers")

注意： BqLog 目前未发布到 CocoaPods 或 Swift Package Manager，请从 Releases 页面下载 xcframework 进行集成。

Java / Kotlin（Android / Server）

Android

  • Maven Central（推荐）

    在 app/build.gradle.kts 中添加：

    android {
    buildFeatures {
        prefab = true   // 启用 Prefab，C++ 侧才能通过 find_package 找到头文件和 .so
    }
}

dependencies {
    implementation("com.tencent.bqlog:android:2.+")
}

    import bq.log;

bq.log myLog = bq.log.create_log("myApp", """
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
""");
myLog.info("Hello from Android Java!");

    C++（NDK）通过 Prefab 使用 — 在 CMakeLists.txt 中添加：

    find_package(BqLog REQUIRED CONFIG)

target_link_libraries(${CMAKE_PROJECT_NAME}
    bqlog::BqLog
    android
    log)

    C++ 代码中直接包含：

    #include "bq_log/bq_log.h"

  • 手动引入 AAR

    从 Releases 页面 下载 android_libs_{version}，将其中的 bqlog-release.aar 复制到项目的 libs/ 目录，然后在 app/build.gradle.kts 中添加：

    android {
    buildFeatures {
        prefab = true
    }
}

dependencies {
    implementation(files("libs/bqlog-release.aar"))
}

    Java / Kotlin 与 C++（NDK）的使用方式与 Maven 方式完全相同。

Java（Server / Desktop）

  • Maven Central（推荐）

    fat JAR 内已打包全平台 native 库（Windows x86_64/arm64、Linux x86_64/arm64/x86、macOS universal、FreeBSD、OpenBSD、NetBSD、DragonFlyBSD、SunOS），运行时自动解压并加载对应平台的库文件，无需额外配置。

    Maven (pom.xml)：

    <dependency>
    <groupId>com.tencent.bqlog</groupId>
    <artifactId>java</artifactId>
    <version>[2.0,3.0)</version>
</dependency>

    Gradle (build.gradle.kts)：

    dependencies {
    implementation("com.tencent.bqlog:java:2.+")
}

    import bq.log;

bq.log myLog = bq.log.create_log("myApp", """
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
""");
myLog.info("Hello from Java! value: {}", 3.14);

  • 手动引入 JAR

    从 Releases 页面 下载对应平台的动态库 {os}_{arch}_libs_{version}，再下载 java_wrapper_{version}，将 JAR 加入 classpath，运行时通过 -Djava.library.path=/path/to/lib 指定 native 库目录。

HarmonyOS / OpenHarmony（ArkTS / C++）

HarmonyOS NEXT 和 OpenHarmony（4.1+ / API 11+）共用 ohpm 上同一个 bqlog 包：底层 .so 在两边二进制兼容，ArkTS Wrapper 只用公共 API，不需要单独发包或单独配置。

集成方式

  • ohpm（推荐）

    ohpm install bqlog

    或在模块的 oh-package.json5 中添加：

    "dependencies": {
    "bqlog": "latest"
}

  • 手动引入 har

    从 Releases 页面 下载 harmony_os_libs_{version}，将其中的 .har 文件复制到项目中，然后在模块的 oh-package.json5 中添加：

    "dependencies": {
    "bqlog": "file:./path/to/bqlog.har"
}

支持在 ArkTS 侧直接调用，也支持在 Native C++ 侧调用。HarmonyOS NEXT 和 OpenHarmony 上行为一致，使用方式完全相同。

C++（Native）使用方式

引入 har 包后（无论 ohpm 还是手动方式），在你的 Native 模块的 CMakeLists.txt 中添加：

find_package(BqLog)

target_link_libraries(${CMAKE_PROJECT_NAME} PUBLIC bqlog::BqLog)

然后在 C++ 代码中直接包含：

#include "bq_log/bq_log.h"

Node.js

  • 支持 CommonJS 与 ES Module。
  • npm（推荐）：
npm install @pippocao/bqlog
  • 手动安装 — 从 Releases 下载 nodejs_npm_{version} 包，解压后找到其中的 pippocao-bqlog-{version}.tgz，通过 npm 安装：
npm install ./pippocao-bqlog-{version}.tgz

可参考仓库下 /demo/nodejs 目录。

Python

  • 支持 Python 3.7+（CPython C Extension，Stable ABI）。
  • pip（推荐）：
pip install bqlog
  • 手动安装 — 从 Releases 下载 python_wrapper_{version} 包，解压后找到 .whl 文件，通过 pip 安装：
pip install ./bqlog-{version}-cp37-abi3-{platform}.whl

可参考仓库下 /demo/python 目录。

Unity / 团结引擎 / Unreal Engine

完整引擎集成步骤请见 游戏引擎集成指南，包括：

  • Unity 和团结引擎 Package 导入
  • Unreal Engine 插件（通过 Fab、预编译版或源码版，支持 UE4、UE5 与当前 UE6 开发版；UE6 仅通过 GitHub Release 提供）
  • FString / FName / FText 支持
  • BqLog 输出重定向到 Unreal Output Log 窗口
  • 蓝图使用方式

快速上手 Demo

C++

#include <string>
#include <bq_log/bq_log.h>

int main() {
    // 配置：输出到控制台
    std::string config = R"(
        appenders_config.appender_console.type=console
        appenders_config.appender_console.levels=[all]
    )";
    auto log = bq::log::create_log("main_log", config);

    log.info("Hello BqLog 2.0! int:{}, float:{}", 123, 3.14f);
    log.force_flush(); // 强制刷新（通常用于程序退出前）

    return 0;
}

更多示例可参考仓库下的 /demo/cpp 目录。

TypeScript — Node.js

import { bq } from "@pippocao/bqlog"; // ESM 写法
// const { bq } = require("@pippocao/bqlog"); // CommonJS 写法

const config = `
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
`;
const log = bq.log.create_log("node_log", config);

log.info("Hello from Node.js! params: {}, {}", "text", 123);
bq.log.force_flush_all_logs();

更多示例可参考仓库下的 /demo/nodejs 目录。

TypeScript — 鸿蒙 ArkTS

import { bq } from "bqlog"; // ohpm 包名

const config = `
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
`;
const log = bq.log.create_log("ohos_log", config);

log.info("Hello from HarmonyOS! params: {}, {}", "text", 123);
bq.log.force_flush_all_logs();

Python

from bq.log import log

config = """
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
"""
my_log = log.create_log("python_log", config)
my_log.info("Hello from Python! params: {}, {}", "text", 123)
log.force_flush_all_logs()

更多示例可参考仓库下的 /demo/python 目录。

C#

string config = @"
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
";
var log = bq.log.create_log("cs_log", config);
log.info("Hello C#! value:{}", 42);

更多示例可参考仓库下的 /demo/csharp 目录。

Java（Android / Server）

String config = """
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
""";
bq.log.Log log = bq.log.Log.createLog("java_log", config);
log.info("Hello Java! value: {}", 3.14);

更多示例可参考仓库下的 /demo/java 目录。

接下来