@kylincloud/flamegraph-vue

一个可复用的火焰图 / 差分火焰图组件库（Vue 3 适配层），基于 Pyroscope flamegraph 思路，适用于 CPU / 内存等采样型 Profiling 数据。

说明：本包主要服务于内部项目，API 在 0.x 阶段可能会有不兼容调整，请以当前版本导出的实际 API 为准。

功能特性

• 支持单视图与 Diff 差分视图
• 支持表格 / 火焰图 / 表格 + 火焰图 / Sandwich 等布局
• 交互：悬停提示、点击缩放、滚轮缩放、拖拽平移、右键菜单
• 函数名搜索与高亮
• 内置 i18n，中英文自动切换
• 两轴主题：themePreset + themeMode，支持自动跟随宿主暗色状态
• 保留 colorMode 兼容，Web Worker 加速

安装

# npm
npm install @kylincloud/flamegraph-vue

# pnpm
pnpm add @kylincloud/flamegraph-vue

依赖 @kylincloud/flamegraph-core 已由本包内部引入，一般不需要在业务侧单独安装。

peer 依赖：

• vue >= 3.3.0
• true-myth ^5.1.2
• zod ^3.11.6

快速上手

<template>
  <FlamegraphRendererVue
    :profile="profile"
    theme-preset="kylin"
    theme-mode="auto"
    locale="zh-CN"
  />
</template>

<script setup lang="ts">
import { shallowRef } from 'vue'
import { FlamegraphRendererVue } from '@kylincloud/flamegraph-vue'
import type { Profile } from '@kylincloud/flamegraph-vue'

const profile = shallowRef<Profile>({
  version: 1,
  flamebearer: {
    names: ['total', 'fnA', 'fnB'],
    levels: [[0, 100, 0, 0]],
    numTicks: 100,
    maxSelf: 100,
  },
  metadata: {
    appName: 'demo',
    spyName: 'cpu',
    format: 'single',
    sampleRate: 100,
    units: 'samples',
  },
})
</script>

推荐使用 profile prop 而非 flamebearer。profile 会自动处理 delta 编码的解码。

主题模型

推荐使用新主题 API：

<FlamegraphRendererVue
  :profile="profile"
  theme-preset="kylin"
  theme-mode="auto"
/>

• themePreset?: 'default' | 'kylin'
• themeMode?: 'auto' | 'light' | 'dark'
• themeMode="auto" 会优先检查最近宿主节点上的暗色标记，并兼容 html.dark、data-theme="dark"、data-theme-mode="dark"、data-flamegraph-theme-mode="dark"
• 渲染器默认值为 themePreset="kylin"、themeMode="auto"

旧 API 继续兼容，映射关系如下：

• colorMode="dark" => themePreset="default" + themeMode="dark"
• colorMode="light" => themePreset="default" + themeMode="light"
• colorMode="kylin" => themePreset="kylin" + themeMode="light"
• 如果新旧 API 同时传入，themePreset / themeMode 优先

推荐宿主接入方式：

• 品牌皮肤固定为麒麟风格时，直接传 theme-preset="kylin" theme-mode="auto"
• 宿主不需要再手动根据 isDark 在 dark / kylin 之间切换
• 右键菜单等 Teleport 到 body 的节点会继承组件解析后的主题，无需业务额外处理

数据格式

interface Profile {
  version: number
  flamebearer: {
    names: string[]
    levels: number[][]
    numTicks: number
    maxSelf: number
    sampleRate?: number
    units?: string
    leftTicks?: number
    rightTicks?: number
  }
  metadata: {
    appName?: string
    spyName?: string
    format: 'single' | 'double'
    sampleRate: number
    units: string
  }
}

数据格式说明：

• 单视图（single）：每 4 个数字为一组 [offset, total, self, nameIndex]
• 差分视图（double）：每 7 个数字为一组 [leftOffset, leftTotal, leftSelf, rightOffset, rightTotal, rightSelf, nameIndex]