Vue-DevTools原理、实现与使用技巧

// Vue 3 源码中的 DevTools Hook 注册
if (typeof __VUE_DEVTOOLS_GLOBAL_HOOK__ !== 'undefined') {
    hook = __VUE_DEVTOOLS_GLOBAL_HOOK__;
    // 注册 Vue 实例
    hook.app = app;
    // 监听组件事件
    hook.on('component:added', (app, uid) => {
        // 通知 DevTools 新组件创建
    });
    hook.on('component:removed', (app, uid) => {
        // 通知 DevTools 组件销毁
    });
    hook.on('component:updated', (app, uid) => {
        // 通知 DevTools 组件更新
    });
}

const instance = {
    uid,                    // 组件唯一 ID
    type,                   // 组件定义对象
    vnode,                  // 虚拟 DOM 节点
    props,                  // 组件 Props
    attrs,                  // 非 Prop 的属性
    setupState,             // setup() 返回的状态
    data,                   // data() 返回的状态
    ctx,                    // 渲染上下文
    refs,                   // template refs
    emit,                   // 事件触发函数
    subTree,                // 渲染的子树
    component,              // 组件定义
    parent,                 // 父组件实例
    appContext,             // 应用上下文
    // ...
};

// 组件节点数据结构
const componentNode = {
    uid: 0,              // 唯一 ID
    name: 'App',         // 组件名
    filePath: 'src/App.vue',  // 文件路径
    isFragment: false,   // 是否 Fragment
    children: [],        // 子组件列表

    // 属性数据
    props: {},           // Props
    data: {},            // Data
    setupState: {},      // Setup 返回的状态
    computed: [],        // 计算属性列表
    inject: {},          // Inject
    provides: {},        // Provide
    emits: [],           // Emits 列表
    refs: {},            // Template Refs
};

function traverseComponentTree(instance, depth = 0) {
    if (!instance) return null;

    const node = {
        uid: instance.uid,
        name: getComponentName(instance),
        depth,
        children: [],
    };

    // 遍历子树
    const subTree = instance.subTree;

    // 处理 Fragment（多根节点组件）
    if (subTree.type === Symbol.for('v-fgt')) {
        // Fragment 有多个子节点
        const children = subTree.children || [];
        for (const child of children) {
            if (child.component) {
                node.children.push(
                    traverseComponentTree(child.component, depth + 1)
                );
            }
        }
    } else if (subTree.component) {
        // 单子组件
        node.children.push(
            traverseComponentTree(subTree.component, depth + 1)
        );
    }

    // 处理 KeepAlive 缓存的组件
    if (instance.type.__keepAlive) {
        const deactivated = instance.keepAliveInstance?.deactivated || [];
        for (const cached of deactivated) {
            node.children.push(
                traverseComponentTree(cached, depth + 1)
            );
        }
    }

    return node;
}

function getComponentName(instance) {
    // 优先级：name 属性 > displayName > 文件名 > Anonymous
    if (instance.type.name) return instance.type.name;
    if (instance.type.displayName) return instance.type.displayName;
    if (instance.type.__file) {
        return instance.type.__file
            .split('/')
            .pop()
            .replace(/\.\w+$/, '');
    }
    return 'Anonymous';
}

function renderComponentTree(tree) {
    const container = document.getElementById('component-tree');
    container.innerHTML = '';
    renderNode(tree, container, 0);
}

function renderNode(node, container, depth) {
    const div = document.createElement('div');
    div.style.paddingLeft = `${depth * 16}px`;
    div.style.cursor = 'pointer';
    div.textContent = `<${node.name} />`;
    div.className = 'component-node';

    // 点击选中
    div.addEventListener('click', () => {
        document.querySelectorAll('.component-node.selected')
            .forEach(el => el.classList.remove('selected'));
        div.classList.add('selected');
        showComponentDetail(node);
    });

    container.appendChild(div);

    if (node.children) {
        node.children.forEach(child => renderNode(child, container, depth + 1));
    }
}

async function getComponentState(instance) {
    const state = {};

    // Props
    if (instance.props && Object.keys(instance.props).length) {
        state.props = instance.props;
    }

    // Data
    if (instance.data && Object.keys(instance.data).length) {
        state.data = instance.data;
    }

    // Setup State（Composition API）
    if (instance.setupState && Object.keys(instance.setupState).length) {
        state.setupState = filterSetupState(instance.setupState);
    }

    // Computed
    const computed = getComputedProperties(instance);
    if (computed.length) {
        state.computed = computed;
    }

    // Inject
    if (instance.provides) {
        state.inject = instance.provides;
    }

    // Provide
    if (instance.provides) {
        state.provides = filterProvides(instance.provides);
    }

    return state;
}

// 过滤 Setup State（去除内部属性）
function filterSetupState(setupState) {
    const filtered = {};
    for (const [key, value] of Object.entries(setupState)) {
        // 跳过以 _ 开头的内部属性和 template ref
        if (key.startsWith('_') || key.startsWith('__')) continue;
        if (isRef(value)) {
            filtered[key] = value.value;  // 自动解包 Ref
        } else if (isReactive(value)) {
            filtered[key] = toRaw(value);  // 转为原始对象
        } else {
            filtered[key] = value;
        }
    }
    return filtered;
}

// 获取计算属性
function getComputedProperties(instance) {
    const computed = [];
    const type = instance.type;

    if (type.computed) {
        for (const [key, getter] of Object.entries(type.computed)) {
            try {
                computed.push({
                    key,
                    value: getter.call(instance.proxy),
                    type: 'computed',
                });
            } catch (e) {
                computed.push({ key, value: '[Error]', type: 'computed' });
            }
        }
    }

    return computed;
}

function showComponentDetail(node) {
    const detail = document.getElementById('component-detail');
    const state = node._rawState;  // 从 Backend 获取的原始状态

    let html = `<h3>&lt;${node.name} /&gt;</h3>`;

    // 按类别展示属性
    const categories = [
        { key: 'props', label: 'Props', icon: '📦' },
        { key: 'data', label: 'Data', icon: '📄' },
        { key: 'setupState', label: 'Setup State', icon: '⚙️' },
        { key: 'computed', label: 'Computed', icon: '🔄' },
        { key: 'inject', label: 'Inject', icon: '💉' },
        { key: 'provides', label: 'Provide', icon: '🤝' },
    ];

    for (const { key, label, icon } of categories) {
        if (state[key]) {
            html += `<h4>${icon} ${label}</h4>`;
            html += renderValueTree(state[key], key);
        }
    }

    detail.innerHTML = html;
}

// 递归渲染值树
function renderValueTree(obj, path, depth = 0) {
    if (depth > 3) return '<span class="max-depth">...</span>';

    let html = '<div class="value-tree">';
    for (const [key, value] of Object.entries(obj)) {
        const currentPath = `${path}.${key}`;
        const type = getType(value);

        html += `<div class="value-item" style="padding-left: ${depth * 16}px">`;
        html += `<span class="key">${key}</span>`;
        html += `<span class="separator">: </span>`;

        if (type === 'object' && value !== null) {
            html += `<span class="type">{${Object.keys(value).length}}</span>`;
            html += renderValueTree(value, currentPath, depth + 1);
        } else if (type === 'array') {
            html += `<span class="type">[${value.length}]</span>`;
            html += renderValueTree(
                Object.fromEntries(value.map((v, i) => [i, v])),
                currentPath, depth + 1
            );
        } else {
            html += `<span class="value ${type}">${formatValue(value)}</span>`;
        }

        html += '</div>';
    }
    html += '</div>';

    return html;
}

// 在页面中高亮组件
function highlightComponent(instance) {
    const el = instance.subTree.el;
    if (!el) return;

    // 移除之前的高亮
    const existingOverlay = document.getElementById('__vue_devtools_overlay__');
    if (existingOverlay) existingOverlay.remove();

    // 创建高亮覆盖层
    const rect = el.getBoundingClientRect();
    const overlay = document.createElement('div');
    overlay.id = '__vue_devtools_overlay__';
    overlay.style.cssText = `
        position: fixed;
        top: ${rect.top}px;
        left: ${rect.left}px;
        width: ${rect.width}px;
        height: ${rect.height}px;
        border: 2px solid #42b883;
        background: rgba(66, 184, 131, 0.1);
        pointer-events: none;
        z-index: 999999;
    `;

    // 添加组件名标签
    const label = document.createElement('div');
    label.style.cssText = `
        position: absolute;
        top: -20px;
        left: 0;
        background: #42b883;
        color: white;
        font-size: 12px;
        padding: 2px 6px;
        border-radius: 2px;
    `;
    label.textContent = `<${getComponentName(instance)} />`;
    overlay.appendChild(label);

    document.body.appendChild(overlay);
}

// 清除高亮
function clearHighlight() {
    const overlay = document.getElementById('__vue_devtools_overlay__');
    if (overlay) overlay.remove();
}

// Timeline 事件类型
const TIMELINE_EVENTS = {
    'component:added': { color: '#42b883', label: 'Mount' },
    'component:updated': { color: '#35495e', label: 'Update' },
    'component:removed': { color: '#ff6b6b', label: 'Unmount' },
    'pinia:mutation': { color: '#ffd859', label: 'Pinia' },
    'router:change': { color: '#6366f1', label: 'Router' },
};

class Timeline {
    constructor() {
        this.events = [];
        this.startTime = performance.now();
    }

    addEvent(type, data) {
        this.events.push({
            type,
            data,
            time: performance.now() - this.startTime,
            color: TIMELINE_EVENTS[type]?.color || '#999',
            label: TIMELINE_EVENTS[type]?.label || type,
        });

        this.render();
    }

    render() {
        const container = document.getElementById('timeline');
        if (!container) return;

        container.innerHTML = this.events.map(event => `
            <div class="timeline-event" style="border-left: 3px solid ${event.color}">
                <span class="time">${event.time.toFixed(1)}ms</span>
                <span class="label">${event.label}</span>
                <span class="detail">${event.data}</span>
            </div>
        `).join('');
    }
}

// vite-plugin-vue-devtools 简化实现
export default function vueDevToolsPlugin() {
    return {
        name: 'vite-plugin-vue-devtools',

        configureServer(server) {
            // 添加 DevTools 中间件
            server.middlewares.use('/__devtools/', devToolsMiddleware());

            // 添加 WebSocket 通信
            server.ws.on('devtools:component-tree', (data) => {
                // 接收组件树数据
            });

            server.ws.on('devtools:select-component', (data) => {
                // 选中组件
            });
        },

        transformIndexHtml(html) {
            // 在 HTML 中注入 DevTools Hook 和 UI
            return html.replace(
                '</body>',
                `
                <script>
                    // 注入 DevTools Hook
                    window.__VUE_DEVTOOLS_GLOBAL_HOOK__ = ${hookCode};
                </script>
                <script type="module" src="/@id/vite-plugin-vue-devtools/client"></script>
                </body>
                `
            );
        },
    };
}

// 在组件中记录自定义事件
import { useDevtoolsTimeline } from 'vite-plugin-vue-devtools';

const { addTimelineEvent } = useDevtoolsTimeline();

addTimelineEvent({
    label: 'Data loaded',
    time: Date.now(),
    data: { count: items.length },
});

// stores/user.js
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
    state: () => ({
        name: 'Guest',
        age: 0,
    }),
    actions: {
        setName(name) {
            this.name = name;
        },
    },
    // 开启 DevTools 调试
    pinia: {
        devtools: true,
    },
});

// ❌ ref 的值需要 .value，调试时不够直观
const count = ref(0);
const name = ref('');

// ✅ reactive 对象在 DevTools 中更易读
const state = reactive({
    count: 0,
    name: '',
});

// ❌ 匿名组件在 DevTools 中显示为 <Anonymous>
export default {
    setup() { /* ... */ },
};

// ✅ 有名组件在 DevTools 中显示为 <UserCard>
export default {
    name: 'UserCard',
    setup() { /* ... */ },
};

<!-- Vue 3.3+ 自动推断 name -->
<script setup>
// 自动使用文件名作为组件名
</script>

// 在组件中添加自定义调试信息
import { defineDevtoolsOverlay } from 'vite-plugin-vue-devtools';

defineDevtoolsOverlay({
    label: 'My Custom Tab',
    icon: '🔧',
    component: CustomDevtoolsPanel,
});

// 在 DevTools 的 Timeline 中查看 watchEffect 的执行
watchEffect(() => {
    console.log('User changed:', user.name);
    // DevTools Timeline 中会显示这次 watchEffect 的执行
});