@vitarx/plugin-vite 1.0.1 → 1.0.2

package/dist/hmr-client/index.d.ts

@@ -11,6 +11,11 @@ declare module 'vitarx' {
         [HMR.state]?: Record<string, any>;
     }
 }
+/**
+ * HMR管理器
+ *
+ * 此管理器负责管理模块和组件的映射关系，并在模块更新时，更新对应的组件。
+ */
 export default class HMRManager {
     #private;
     /**
@@ -25,11 +30,11 @@ export default class HMRManager {
      */
     bindId(component: Function, id: string): void;
     /**
-     * 置换新模块
+     * 置换新组件
      *
      * 此方法提供给`createView`函数调用，保持每次创建组件实例都是最新的模块！
      *
-     * @param component
+     * @param component - 组件构造函数
      */
     resolveComponent(component: Component): Component;
     /**
@@ -49,10 +54,15 @@ export default class HMRManager {
      */
     register(view: ComponentView, component?: Component): void;
     /**
-     * 获取模块id
+     * 获取组件的唯一id
      *
-     * @param component
+     * @param component - 组件构造函数
      */
     getId(component: Component): string;
-    update(mod: ModuleNamespace): void;
+    /**
+     * 模块更新
+     *
+     * @param newModule - 新模块对象
+     */
+    update(newModule: ModuleNamespace): void;
 }

package/dist/hmr-client/index.js

@@ -4,9 +4,14 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _HMRManager_idMapToView, _HMRManager_idMapToComponent;
-import { isReactive, isRef } from 'vitarx';
+import { isComponent, isReactive, isRef } from 'vitarx';
 import { HMR } from '../constants/index.js';
 import { processUpdate } from './update.js';
+/**
+ * HMR管理器
+ *
+ * 此管理器负责管理模块和组件的映射关系，并在模块更新时，更新对应的组件。
+ */
 class HMRManager {
     constructor() {
         /**
@@ -49,11 +54,11 @@ class HMRManager {
         }
     }
     /**
-     * 置换新模块
+     * 置换新组件
      *
      * 此方法提供给`createView`函数调用，保持每次创建组件实例都是最新的模块！
      *
-     * @param component
+     * @param component - 组件构造函数
      */
     resolveComponent(component) {
         const id = this.getId(component);
@@ -95,38 +100,55 @@ class HMRManager {
         }
     }
     /**
-     * 获取模块id
+     * 获取组件的唯一id
      *
-     * @param component
+     * @param component - 组件构造函数
      */
     getId(component) {
         return Reflect.get(component, HMR.id);
     }
-    update(mod) {
-        if (!mod)
+    /**
+     * 模块更新
+     *
+     * @param newModule - 新模块对象
+     */
+    update(newModule) {
+        if (!newModule)
             return;
         try {
-            for (const modKey in mod) {
-                // 新模块
-                const newComponent = mod[modKey];
-                // 模块id
-                const moduleId = this.getId(newComponent);
-                // 模块ID不存在，跳过
-                if (!moduleId)
+            const components = [];
+            const updatedView = new Set();
+            // 先遍历模块更新id->component映射
+            for (const modKey in newModule) {
+                // 新组件
+                const newComponent = newModule[modKey];
+                // 如果不是组件则跳过
+                if (!isComponent(newComponent))
                     continue;
+                // 更新模块
+                const id = this.getId(newComponent);
+                if (id) {
+                    __classPrivateFieldGet(this, _HMRManager_idMapToComponent, "f").set(id, newComponent);
+                    components.push(newComponent);
+                }
+            }
+            for (const component of components) {
+                const id = this.getId(component);
                 // 模块活跃的虚拟节点集合
-                const nodes = __classPrivateFieldGet(this, _HMRManager_idMapToView, "f").get(moduleId);
-                // 模块不存在，跳过
-                if (!nodes)
+                const views = __classPrivateFieldGet(this, _HMRManager_idMapToView, "f").get(id);
+                if (!views)
                     continue;
-                for (const node of nodes) {
-                    // 更新模块
-                    const id = this.getId(newComponent);
-                    if (id)
-                        __classPrivateFieldGet(this, _HMRManager_idMapToComponent, "f").set(id, newComponent);
-                    // 更新节点视图
-                    if ((node.isActive || node.active) && node.isMounted) {
-                        processUpdate(node, newComponent);
+                // 遍历关联的所有视图，使其更新
+                for (const view of views) {
+                    // 跳过已更新过的视图，避免同一次更新中同一个视图被更新多次
+                    if (updatedView.has(view))
+                        continue;
+                    // 仅在视图是活跃状态，且已挂载时才更新
+                    if (view.isActive && view.isMounted) {
+                        // 处理视图更新
+                        processUpdate(view, this.resolveComponent(view.component));
+                        // 标记视图已更新
+                        updatedView.add(view);
                     }
                 }
             }

package/dist/passes/hmr/inject-imports.d.ts

@@ -4,7 +4,10 @@
  * @module passes/hmr/inject-imports
  */
 import * as t from '@babel/types';
-/** getComponentView 的内部别名，避免与用户代码冲突 */
+/**
+ * getComponentView 的内部别名，使用特殊命名避免与用户代码冲突
+ * 格式：__$VITARX_XXX$__
+ */
 export declare const GET_COMPONENT_VIEW_ALIAS = "__$VITARX_GET_COMPONENT_VIEW$__";
 /**
  * 注入 HMR 客户端导入

package/dist/passes/hmr/inject-imports.js

@@ -5,14 +5,19 @@
  */
 import * as t from '@babel/types';
 import { HMR } from '../../constants/index.js';
-/** getComponentView 的内部别名，避免与用户代码冲突 */
+/**
+ * getComponentView 的内部别名，使用特殊命名避免与用户代码冲突
+ * 格式：__$VITARX_XXX$__
+ */
 export const GET_COMPONENT_VIEW_ALIAS = '__$VITARX_GET_COMPONENT_VIEW$__';
 /**
  * 注入 HMR 客户端导入
  * @param program - AST Program 节点
  */
 export function injectHMRImport(program) {
+    // 创建 import 语句: import __$VITARX_HMR$__ from '@vitarx/vite-plugin/hmr-client'
     const importDecl = t.importDeclaration([t.importDefaultSpecifier(t.identifier(HMR.manager))], t.stringLiteral('@vitarx/vite-plugin/hmr-client'));
+    // 将导入语句插入到程序体最前面
     program.body.unshift(importDecl);
 }
 /**
@@ -21,6 +26,8 @@ export function injectHMRImport(program) {
  * @param program - AST Program 节点
  */
 export function injectGetComponentViewImport(program) {
+    // 创建 import 语句: import { getComponentView as __$VITARX_GET_COMPONENT_VIEW$__ } from 'vitarx'
     const importDecl = t.importDeclaration([t.importSpecifier(t.identifier(GET_COMPONENT_VIEW_ALIAS), t.identifier('getComponentView'))], t.stringLiteral('vitarx'));
+    // 将导入语句插入到程序体最前面
     program.body.unshift(importDecl);
 }

package/dist/passes/hmr/inject-state.d.ts

@@ -6,24 +6,29 @@
 import * as t from '@babel/types';
 /**
  * 创建组件函数体内的 HMR 注册代码
+ * 生成的代码包括：获取视图节点、注册到 HMR 管理器、保存状态
  * @param variableNames - 需要追踪的变量名列表
  * @returns HMR 注册语句数组
  */
 export declare function createHMRRegistrationStatements(variableNames: string[]): t.Statement[];
 /**
  * 创建包装组件的 HMR 注册代码
- * 只注册节点，不保存状态，传入组件函数自身作为第二个参数
+ * 包装组件（如 defineComponent、builder）只注册节点，不保存状态
+ * 传入组件函数自身作为第二个参数，便于更新时重新执行包装函数
  * @param componentName - 组件函数名称
  * @returns HMR 注册语句数组
  */
 export declare function createWrappedComponentHMRStatements(componentName: string): t.Statement[];
 /**
  * 从函数体中收集局部变量名
+ * 递归遍历函数体中的所有变量声明，用于状态恢复
  * @param functionBody - 函数体语句块
  * @returns 变量名数组
  */
 export declare function collectLocalVariableNames(functionBody: t.BlockStatement): string[];
 /**
  * 为函数体内的变量声明注入状态恢复代码
+ * 遍历函数体中的所有变量声明语句
+ * @param functionBody - 函数体语句块
  */
 export declare function injectStatePreservation(functionBody: t.BlockStatement): void;

package/dist/passes/hmr/inject-state.js

@@ -9,16 +9,26 @@ import { collectPatternBindings } from '../../utils/index.js';
 import { GET_COMPONENT_VIEW_ALIAS } from './inject-imports.js';
 /**
  * 创建组件函数体内的 HMR 注册代码
+ * 生成的代码包括：获取视图节点、注册到 HMR 管理器、保存状态
  * @param variableNames - 需要追踪的变量名列表
  * @returns HMR 注册语句数组
  */
 export function createHMRRegistrationStatements(variableNames) {
     const statements = [];
+    // 语句1: const __$VITARX_HMR_VIEW_NODE$__ = __$VITARX_GET_COMPONENT_VIEW$__(true)
+    // 获取当前组件的视图节点
     statements.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier(HMR.view), t.callExpression(t.identifier(GET_COMPONENT_VIEW_ALIAS), [t.booleanLiteral(true)]))
     ]));
+    // 语句2: __$VITARX_HMR$__.instance.register(__$VITARX_HMR_VIEW_NODE$__)
+    // 将视图节点注册到 HMR 管理器
     statements.push(t.expressionStatement(t.callExpression(t.memberExpression(t.memberExpression(t.identifier(HMR.manager), t.identifier('instance')), t.identifier('register')), [t.identifier(HMR.view)])));
+    // 构建状态对象的 getter 属性，延迟求值避免不必要的计算
     const stateProperties = variableNames.map(name => t.objectMethod('get', t.identifier(name), [], t.blockStatement([t.returnStatement(t.identifier(name))])));
+    // 语句3: __$VITARX_HMR_VIEW_NODE$__ && Promise.resolve().then(() => {
+    //   __$VITARX_HMR_VIEW_NODE$__.__$vitarx_hmr_state$__ = { get 变量名() { return 变量名 } }
+    // })
+    // 异步保存状态到视图节点，确保 DOM 更新完成后再保存
     statements.push(t.expressionStatement(t.logicalExpression('&&', t.identifier(HMR.view), t.callExpression(t.memberExpression(t.callExpression(t.memberExpression(t.identifier('Promise'), t.identifier('resolve')), []), t.identifier('then')), [
         t.arrowFunctionExpression([], t.blockStatement([
             t.expressionStatement(t.assignmentExpression('=', t.memberExpression(t.identifier(HMR.view), t.identifier(HMR.state)), t.objectExpression(stateProperties)))
@@ -28,20 +38,25 @@ export function createHMRRegistrationStatements(variableNames) {
 }
 /**
  * 创建包装组件的 HMR 注册代码
- * 只注册节点，不保存状态，传入组件函数自身作为第二个参数
+ * 包装组件（如 defineComponent、builder）只注册节点，不保存状态
+ * 传入组件函数自身作为第二个参数，便于更新时重新执行包装函数
  * @param componentName - 组件函数名称
  * @returns HMR 注册语句数组
  */
 export function createWrappedComponentHMRStatements(componentName) {
     const statements = [];
+    // 语句1: const __$VITARX_HMR_VIEW_NODE$__ = __$VITARX_GET_COMPONENT_VIEW$__(true)
     statements.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier(HMR.view), t.callExpression(t.identifier(GET_COMPONENT_VIEW_ALIAS), [t.booleanLiteral(true)]))
     ]));
+    // 语句2: __$VITARX_HMR$__.instance.register(__$VITARX_HMR_VIEW_NODE$__, Component)
+    // 第二个参数传入组件函数，支持热更新时重新执行
     statements.push(t.expressionStatement(t.callExpression(t.memberExpression(t.memberExpression(t.identifier(HMR.manager), t.identifier('instance')), t.identifier('register')), [t.identifier(HMR.view), t.identifier(componentName)])));
     return statements;
 }
 /**
  * 从函数体中收集局部变量名
+ * 递归遍历函数体中的所有变量声明，用于状态恢复
  * @param functionBody - 函数体语句块
  * @returns 变量名数组
  */
@@ -50,20 +65,35 @@ export function collectLocalVariableNames(functionBody) {
     collectFromBlock(functionBody, variableNames);
     return Array.from(variableNames);
 }
+/**
+ * 从语句块中收集变量名
+ * @param block - 语句块节点
+ * @param variableNames - 存储变量名的集合
+ */
 function collectFromBlock(block, variableNames) {
+    // 遍历语句块中的每个语句
     for (const stmt of block.body) {
         collectFromStatement(stmt, variableNames);
     }
 }
+/**
+ * 从单个语句中收集变量名
+ * 支持多种语句类型：变量声明、条件语句、循环语句、switch、try-catch 等
+ * @param stmt - 语句节点
+ * @param variableNames - 存储变量名的集合
+ */
 function collectFromStatement(stmt, variableNames) {
+    // 处理变量声明语句：const/let/var
     if (stmt.type === 'VariableDeclaration') {
         for (const decl of stmt.declarations) {
+            // 跳过 void 模式（如 void 0）
             if (decl.id.type !== 'VoidPattern') {
                 collectPatternBindings(decl.id, variableNames);
             }
         }
     }
     else if (stmt.type === 'IfStatement') {
+        // 递归处理 if 语句的两个分支
         if (stmt.consequent.type === 'BlockStatement') {
             collectFromBlock(stmt.consequent, variableNames);
         }
@@ -80,6 +110,7 @@ function collectFromStatement(stmt, variableNames) {
         }
     }
     else if (stmt.type === 'ForStatement' || stmt.type === 'WhileStatement' || stmt.type === 'DoWhileStatement') {
+        // 处理 for/while/do-while 循环
         if (stmt.body.type === 'BlockStatement') {
             collectFromBlock(stmt.body, variableNames);
         }
@@ -88,6 +119,7 @@ function collectFromStatement(stmt, variableNames) {
         }
     }
     else if (stmt.type === 'ForInStatement' || stmt.type === 'ForOfStatement') {
+        // 处理 for...in/for...of 循环
         if (stmt.body.type === 'BlockStatement') {
             collectFromBlock(stmt.body, variableNames);
         }
@@ -96,9 +128,11 @@ function collectFromStatement(stmt, variableNames) {
         }
     }
     else if (stmt.type === 'BlockStatement') {
+        // 处理嵌套语句块
         collectFromBlock(stmt, variableNames);
     }
     else if (stmt.type === 'SwitchStatement') {
+        // 处理 switch 语句，遍历所有 case
         for (const c of stmt.cases) {
             for (const s of c.consequent) {
                 collectFromStatement(s, variableNames);
@@ -106,6 +140,7 @@ function collectFromStatement(stmt, variableNames) {
         }
     }
     else if (stmt.type === 'TryStatement') {
+        // 处理 try-catch-finally
         collectFromBlock(stmt.block, variableNames);
         if (stmt.handler) {
             collectFromBlock(stmt.handler.body, variableNames);
@@ -117,35 +152,53 @@ function collectFromStatement(stmt, variableNames) {
 }
 /**
  * 判断表达式是否为函数类型
+ * 函数类型不需要状态恢复（函数定义本身不会改变）
+ * @param expr - 表达式节点
+ * @returns 是否为函数类型
  */
 function isFunctionExpression(expr) {
     if (!expr)
         return false;
-    return (expr.type === 'ArrowFunctionExpression' ||
-        expr.type === 'FunctionExpression' ||
-        expr.type === 'ClassExpression');
+    return (expr.type === 'ArrowFunctionExpression' || // 箭头函数
+        expr.type === 'FunctionExpression' || // 函数表达式
+        expr.type === 'ClassExpression' // 类表达式
+    );
 }
 /**
  * 创建状态恢复表达式
  * 格式：__$VITARX_HMR$__.instance.memo(__$VITARX_HMR_VIEW_NODE$__, '变量名') ?? 原始初始值
+ * 如果 memo 方法返回保存的状态则使用，否则使用原始初始值
+ * @param variableName - 变量名
+ * @param originalInit - 原始初始化表达式
+ * @returns 状态恢复表达式
  */
 function createMemoExpression(variableName, originalInit) {
-    return t.logicalExpression('??', t.callExpression(t.memberExpression(t.memberExpression(t.identifier(HMR.manager), t.identifier('instance')), t.identifier('memo')), [t.identifier(HMR.view), t.stringLiteral(variableName)]), originalInit);
+    return t.logicalExpression('??', // 使用空值合并运算符
+    t.callExpression(t.memberExpression(t.memberExpression(t.identifier(HMR.manager), t.identifier('instance')), t.identifier('memo')), [t.identifier(HMR.view), t.stringLiteral(variableName)]), originalInit // 原始初始值作为 fallback
+    );
 }
 /**
  * 为单个变量声明注入状态恢复代码
+ * 将 const x = value 转换为 const x = memo(view, 'x') ?? value
+ * @param decl - 变量声明节点
  */
 function injectStatePreservationForDeclaration(decl) {
+    // 只处理标识符形式的变量名（跳过解构赋值）
     if (decl.id.type !== 'Identifier')
         return;
+    // 跳过没有初始值的声明
     if (!decl.init)
         return;
+    // 跳过函数类型的初始值（不需要状态恢复）
     if (isFunctionExpression(decl.init))
         return;
+    // 替换初始值为状态恢复表达式
     decl.init = createMemoExpression(decl.id.name, decl.init);
 }
 /**
  * 为函数体内的变量声明注入状态恢复代码
+ * 遍历函数体中的所有变量声明语句
+ * @param functionBody - 函数体语句块
  */
 export function injectStatePreservation(functionBody) {
     for (const stmt of functionBody.body) {

package/dist/passes/hmr/inject.d.ts

@@ -10,6 +10,6 @@ import type { ComponentInfo } from '../../utils/index.js';
  * 主入口函数，为所有组件注入完整的 HMR 支持
  * @param program - AST Program 节点
  * @param components - 组件信息列表
- * @param filename - 文件名
+ * @param filename - 文件名（用于生成组件唯一 ID）
  */
 export declare function injectHMRSupport(program: t.Program, components: ComponentInfo[], filename: string): void;

package/dist/passes/hmr/inject.js

@@ -11,34 +11,47 @@ import { createHMRRegistrationStatements, createWrappedComponentHMRStatements, c
  * 为组件函数注入 HMR 注册代码
  * @param func - 函数声明/表达式/箭头函数
  * @param variableNames - 需要追踪的变量名列表
- * @param isWrapped - 是否为包装组件
+ * @param isWrapped - 是否为包装组件（defineComponent/builder）
  * @param componentName - 组件名称（包装组件需要）
  */
 function injectHMRIntoFunction(func, variableNames, isWrapped = false, componentName) {
+    // 如果是箭头函数且函数体不是块语句（单行箭头函数），转换为块语句
     if (func.type === 'ArrowFunctionExpression' && func.body.type !== 'BlockStatement') {
         const returnStmt = t.returnStatement(func.body);
         func.body = t.blockStatement([returnStmt]);
     }
+    // 确保函数体是块语句
     if (!func.body || func.body.type !== 'BlockStatement')
         return;
+    // 非包装组件需要注入状态恢复代码
     if (!isWrapped) {
         injectStatePreservation(func.body);
     }
+    // 根据组件类型创建对应的 HMR 注册语句
     const statements = isWrapped
         ? createWrappedComponentHMRStatements(componentName)
         : createHMRRegistrationStatements(variableNames);
+    // 将注册语句插入到函数体开头
     func.body.body.unshift(...statements);
 }
 /**
  * 创建 bindId 语句
+ * 将组件名称与唯一 ID 绑定，用于热更新时识别组件
+ * @param componentName - 组件名称
+ * @param componentId - 组件唯一 ID
+ * @returns bindId 调用语句
  */
 function createBindIdStatement(componentName, componentId) {
+    // 生成：__$VITARX_HMR$__.instance.bindId(Component, 'hash')
     return t.expressionStatement(t.callExpression(t.memberExpression(t.memberExpression(t.identifier(HMR.manager), t.identifier('instance')), t.identifier('bindId')), [t.identifier(componentName), t.stringLiteral(componentId)]));
 }
 /**
  * 创建 import.meta.hot.accept 语句
+ * 监听模块热更新事件，触发组件更新
+ * @returns hot.accept 调用语句
  */
 function createHotAcceptStatement() {
+    // 生成：import.meta.hot.accept(mod => { __$VITARX_HMR$__.instance.update(mod) })
     return t.expressionStatement(t.callExpression(t.memberExpression(t.memberExpression(t.memberExpression(t.identifier('import'), t.identifier('meta')), t.identifier('hot')), t.identifier('accept')), [
         t.arrowFunctionExpression([t.identifier('mod')], t.blockStatement([
             t.expressionStatement(t.callExpression(t.memberExpression(t.memberExpression(t.identifier(HMR.manager), t.identifier('instance')), t.identifier('update')), [t.identifier('mod')]))
@@ -47,14 +60,20 @@ function createHotAcceptStatement() {
 }
 /**
  * 生成组件唯一 ID（文件路径 + 组件名称）
+ * 使用 FNV-1a 哈希算法生成短哈希值
+ * @param filename - 文件路径
+ * @param componentName - 组件名称
+ * @returns 组件唯一 ID（十六进制字符串）
  */
 function generateComponentId(filename, componentName) {
     const combined = `${filename}:${componentName}`;
+    // FNV-1a 哈希算法初始值
     let hash = 2166136261;
     for (let i = 0; i < combined.length; i++) {
         hash ^= combined.charCodeAt(i);
         hash = Math.imul(hash, 16777619);
     }
+    // 转换为无符号整数并转为十六进制
     return (hash >>> 0).toString(16);
 }
 /**
@@ -62,19 +81,25 @@ function generateComponentId(filename, componentName) {
  * 主入口函数，为所有组件注入完整的 HMR 支持
  * @param program - AST Program 节点
  * @param components - 组件信息列表
- * @param filename - 文件名
+ * @param filename - 文件名（用于生成组件唯一 ID）
  */
 export function injectHMRSupport(program, components, filename) {
+    // 如果没有组件，直接返回
     if (components.length === 0)
         return;
+    // 步骤1: 注入 HMR 相关的 import 语句
     injectHMRImport(program);
     injectGetComponentViewImport(program);
+    // 步骤2: 为每个组件函数注入 HMR 注册代码和状态恢复
     for (const { node, isWrapped, name } of components) {
+        // 收集函数体内的局部变量名（用于状态保存）
         const variableNames = node.body?.type === 'BlockStatement' ? collectLocalVariableNames(node.body) : [];
         injectHMRIntoFunction(node, variableNames, isWrapped, name);
     }
+    // 步骤3: 为每个组件创建 bindId 语句（用于热更新时识别）
     for (const { name } of components) {
         program.body.push(createBindIdStatement(name, generateComponentId(filename, name)));
     }
+    // 步骤4: 创建 import.meta.hot.accept 语句（监听热更新事件）
     program.body.push(createHotAcceptStatement());
 }

package/dist/passes/imports/collectImports.d.ts

@@ -5,16 +5,16 @@
  */
 import * as t from '@babel/types';
 /**
- * 收集现有导入信息
- * 只收集普通的 import 语句，跳过 import type 语句
+ * 收集现有 vitarx 导入信息
+ * 只收集普通的 import 语句，跳过 import type/typeof 语句
  * @param program - AST Program 节点
- * @returns 本地变量名集合和 vitarx 导入映射
+ * @returns 映射表：导入名 -> 本地别名
  */
 export declare function collectExistingImports(program: t.Program): Map<string, string>;
 /**
  * 收集本地变量绑定
  * 包括导入绑定、变量声明、函数声明、类声明
- * 只收集运行时存在的绑定，跳过 import type
+ * 只收集运行时存在的绑定，跳过 import type/typeof
  * @param program - AST Program 节点
  * @returns 本地变量名集合
  */

package/dist/passes/imports/collectImports.js

@@ -1,26 +1,34 @@
 import { VITARX_MODULE } from '../../constants/index.js';
 import { collectPatternBindings } from '../../utils/index.js';
 /**
- * 收集现有导入信息
- * 只收集普通的 import 语句，跳过 import type 语句
+ * 收集现有 vitarx 导入信息
+ * 只收集普通的 import 语句，跳过 import type/typeof 语句
  * @param program - AST Program 节点
- * @returns 本地变量名集合和 vitarx 导入映射
+ * @returns 映射表：导入名 -> 本地别名
  */
 export function collectExistingImports(program) {
+    // 存储导入名到本地别名的映射
     const vitarxImports = new Map();
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
+        // 跳过非导入声明节点
         if (node.type !== 'ImportDeclaration')
             continue;
+        // 跳过类型导入（不影响运行时）
         if (node.importKind === 'type' || node.importKind === 'typeof')
             continue;
+        // 只处理 vitarx 模块的导入
         const source = node.source.value;
         if (source !== VITARX_MODULE)
             continue;
+        // 遍历导入说明符
         for (const specifier of node.specifiers) {
             if (specifier.type === 'ImportSpecifier') {
+                // 获取导入的原始名称（支持字符串字面量和标识符）
                 const importedName = specifier.imported.type === 'Identifier'
                     ? specifier.imported.name
                     : specifier.imported.value;
+                // 记录导入名到本地别名的映射
                 vitarxImports.set(importedName, specifier.local.name);
             }
         }
@@ -30,31 +38,38 @@ export function collectExistingImports(program) {
 /**
  * 收集本地变量绑定
  * 包括导入绑定、变量声明、函数声明、类声明
- * 只收集运行时存在的绑定，跳过 import type
+ * 只收集运行时存在的绑定，跳过 import type/typeof
  * @param program - AST Program 节点
  * @returns 本地变量名集合
  */
 export function collectLocalBindings(program) {
     const bindings = new Set();
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
+        // 处理导入声明
         if (node.type === 'ImportDeclaration') {
-            // 跳过 import type 和 import typeof 语句
+            // 跳过类型导入（不影响运行时绑定）
             if (node.importKind === 'type' || node.importKind === 'typeof')
                 continue;
+            // 收集所有导入的本地名称
             for (const specifier of node.specifiers) {
                 bindings.add(specifier.local.name);
             }
         }
+        // 处理变量声明（支持解构赋值）
         if (node.type === 'VariableDeclaration') {
             for (const decl of node.declarations) {
+                // 跳过 void 模式（如 void 0）
                 if (decl.id.type !== 'VoidPattern') {
                     collectPatternBindings(decl.id, bindings);
                 }
             }
         }
+        // 处理函数声明
         if (node.type === 'FunctionDeclaration' && node.id) {
             bindings.add(node.id.name);
         }
+        // 处理类声明
         if (node.type === 'ClassDeclaration' && node.id) {
             bindings.add(node.id.name);
         }

package/dist/passes/imports/collectRefVariables.d.ts

@@ -14,7 +14,7 @@ import type { RefApiAliases } from '../../context.js';
 export declare function collectRefApiAliases(program: t.Program): RefApiAliases;
 /**
  * 收集通过 ref API 定义的变量
- * 包括直接赋值和 toRefs 解构
+ * 包括直接赋值（const x = ref(0)）和 toRefs 解构（const { a, b } = toRefs(obj)）
  * @param program - AST Program 节点
  * @param refApiAliases - ref API 别名映射
  * @returns ref 变量名集合
@@ -22,7 +22,7 @@ export declare function collectRefApiAliases(program: t.Program): RefApiAliases;
 export declare function collectRefVariables(program: t.Program, refApiAliases: RefApiAliases): Set<string>;
 /**
  * 收集确定不是 ref 的变量
- * 包括函数声明、箭头函数和函数表达式变量
+ * 包括函数声明、箭头函数和函数表达式变量（这些不可能是 ref）
  * @param program - AST Program 节点
  * @returns 非 ref 变量名集合
  */