@vitarx/plugin-vite 1.0.4 → 1.0.5

package/dist/passes/directives/processDirectives.d.ts

@@ -5,7 +5,7 @@
  */
 import * as t from '@babel/types';
 import { TransformContext } from '../../context.js';
-import type { DirectiveInfo } from '../../passes/props/types.js';
+import type { DirectiveInfo } from '../props/types.js';
 /**
  * 处理指令
  * 将指令转换为 withDirectives 调用

package/dist/passes/directives/processDirectives.js

@@ -52,16 +52,21 @@ ctx // 转换上下文，包含别名、导入等信息
     const properties = []; // 定义对象属性数组，可以是属性或方法
     // 添加 value 属性
     if (isIdentifier(value)) {
-        // 如果值是一个标识符
-        markImport(ctx, 'unref'); // 标记需要导入unref函数
-        const unrefAlias = getAlias(ctx.vitarxAliases, 'unref'); // 获取unref函数的别名
-        properties.push(
-        // 添加一个getter方法作为属性
-        t.objectMethod('get', // 方法类型为getter
-        t.identifier('value'), // 属性名为value
-        [], // 无参数
-        t.blockStatement([t.returnStatement(t.callExpression(t.identifier(unrefAlias), [value]))]) // 返回unref(value)
-        ));
+        // 三态决策：已知 ref → .value，已知非 ref → 原样，未知 → unref()
+        if (ctx.refVariables.has(value.name)) {
+            // 已知 ref：直接使用 .value
+            properties.push(t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(t.memberExpression(value, t.identifier('value')))])));
+        }
+        else if (ctx.nonRefVariables.has(value.name)) {
+            // 已知非 ref（函数等）：原样返回，无需 unref
+            properties.push(t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(value)])));
+        }
+        else {
+            // 未知标识符：使用 unref() 解包（非 ref 原样返回）
+            markImport(ctx, 'unref');
+            const unrefAlias = getAlias(ctx.vitarxAliases, 'unref');
+            properties.push(t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(t.callExpression(t.identifier(unrefAlias), [value]))])));
+        }
     }
     else {
         // 如果值不是标识符

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

@@ -28,7 +28,7 @@ export declare function createWrappedComponentHMRStatements(componentName: strin
 export declare function collectLocalVariableNames(functionBody: t.BlockStatement): string[];
 /**
  * 为函数体内的变量声明注入状态恢复代码
- * 遍历函数体中的所有变量声明语句
+ * 递归遍历所有变量声明（包括 if/for/while/switch/try 嵌套块）
  * @param functionBody - 函数体语句块
  */
 export declare function injectStatePreservation(functionBody: t.BlockStatement): void;

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

@@ -62,94 +62,79 @@ export function createWrappedComponentHMRStatements(componentName) {
  */
 export function collectLocalVariableNames(functionBody) {
     const variableNames = new Set();
-    collectFromBlock(functionBody, variableNames);
+    forEachVariableDeclarator(functionBody, decl => {
+        if (decl.id.type !== 'VoidPattern') {
+            collectPatternBindings(decl.id, variableNames);
+        }
+    });
     return Array.from(variableNames);
 }
 /**
- * 从语句块中收集变量名
+ * 遍历语句块中的所有变量声明，对每个 VariableDeclarator 执行回调
+ * 递归处理嵌套的控制流语句（if/for/while/switch/try 等）
  * @param block - 语句块节点
- * @param variableNames - 存储变量名的集合
+ * @param visitor - 变量声明访问者回调
  */
-function collectFromBlock(block, variableNames) {
-    // 遍历语句块中的每个语句
+function forEachVariableDeclarator(block, visitor) {
     for (const stmt of block.body) {
-        collectFromStatement(stmt, variableNames);
+        traverseStatementForDeclarators(stmt, visitor);
     }
 }
 /**
- * 从单个语句中收集变量名
+ * 从单个语句中递归查找变量声明并执行回调
  * 支持多种语句类型：变量声明、条件语句、循环语句、switch、try-catch 等
  * @param stmt - 语句节点
- * @param variableNames - 存储变量名的集合
+ * @param visitor - 变量声明访问者回调
  */
-function collectFromStatement(stmt, variableNames) {
-    // 处理变量声明语句：const/let/var
+function traverseStatementForDeclarators(stmt, visitor) {
     if (stmt.type === 'VariableDeclaration') {
         for (const decl of stmt.declarations) {
-            // 跳过 void 模式（如 void 0）
-            if (decl.id.type !== 'VoidPattern') {
-                collectPatternBindings(decl.id, variableNames);
-            }
+            visitor(decl);
         }
     }
     else if (stmt.type === 'IfStatement') {
-        // 递归处理 if 语句的两个分支
-        if (stmt.consequent.type === 'BlockStatement') {
-            collectFromBlock(stmt.consequent, variableNames);
-        }
-        else {
-            collectFromStatement(stmt.consequent, variableNames);
-        }
+        traverseBodyForDeclarators(stmt.consequent, visitor);
         if (stmt.alternate) {
-            if (stmt.alternate.type === 'BlockStatement') {
-                collectFromBlock(stmt.alternate, variableNames);
-            }
-            else {
-                collectFromStatement(stmt.alternate, variableNames);
-            }
+            traverseBodyForDeclarators(stmt.alternate, visitor);
         }
     }
     else if (stmt.type === 'ForStatement' || stmt.type === 'WhileStatement' || stmt.type === 'DoWhileStatement') {
-        // 处理 for/while/do-while 循环
-        if (stmt.body.type === 'BlockStatement') {
-            collectFromBlock(stmt.body, variableNames);
-        }
-        else {
-            collectFromStatement(stmt.body, variableNames);
-        }
+        traverseBodyForDeclarators(stmt.body, visitor);
     }
     else if (stmt.type === 'ForInStatement' || stmt.type === 'ForOfStatement') {
-        // 处理 for...in/for...of 循环
-        if (stmt.body.type === 'BlockStatement') {
-            collectFromBlock(stmt.body, variableNames);
-        }
-        else {
-            collectFromStatement(stmt.body, variableNames);
-        }
+        traverseBodyForDeclarators(stmt.body, visitor);
     }
     else if (stmt.type === 'BlockStatement') {
-        // 处理嵌套语句块
-        collectFromBlock(stmt, variableNames);
+        forEachVariableDeclarator(stmt, visitor);
     }
     else if (stmt.type === 'SwitchStatement') {
-        // 处理 switch 语句，遍历所有 case
         for (const c of stmt.cases) {
             for (const s of c.consequent) {
-                collectFromStatement(s, variableNames);
+                traverseStatementForDeclarators(s, visitor);
             }
         }
     }
     else if (stmt.type === 'TryStatement') {
-        // 处理 try-catch-finally
-        collectFromBlock(stmt.block, variableNames);
+        forEachVariableDeclarator(stmt.block, visitor);
         if (stmt.handler) {
-            collectFromBlock(stmt.handler.body, variableNames);
+            forEachVariableDeclarator(stmt.handler.body, visitor);
         }
         if (stmt.finalizer) {
-            collectFromBlock(stmt.finalizer, variableNames);
+            forEachVariableDeclarator(stmt.finalizer, visitor);
         }
     }
 }
+/**
+ * 遍历语句体（可能是 BlockStatement 或单条语句）中的变量声明
+ */
+function traverseBodyForDeclarators(body, visitor) {
+    if (body.type === 'BlockStatement') {
+        forEachVariableDeclarator(body, visitor);
+    }
+    else {
+        traverseStatementForDeclarators(body, visitor);
+    }
+}
 /**
  * 判断表达式是否为函数类型
  * 函数类型不需要状态恢复（函数定义本身不会改变）
@@ -197,15 +182,11 @@ function injectStatePreservationForDeclaration(decl) {
 }
 /**
  * 为函数体内的变量声明注入状态恢复代码
- * 遍历函数体中的所有变量声明语句
+ * 递归遍历所有变量声明（包括 if/for/while/switch/try 嵌套块）
  * @param functionBody - 函数体语句块
  */
 export function injectStatePreservation(functionBody) {
-    for (const stmt of functionBody.body) {
-        if (stmt.type === 'VariableDeclaration') {
-            for (const decl of stmt.declarations) {
-                injectStatePreservationForDeclaration(decl);
-            }
-        }
-    }
+    forEachVariableDeclarator(functionBody, decl => {
+        injectStatePreservationForDeclaration(decl);
+    });
 }

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

@@ -23,6 +23,7 @@ export declare function collectRefVariables(program: t.Program, refApiAliases: R
 /**
  * 收集确定不是 ref 的变量
  * 包括函数声明、箭头函数和函数表达式变量（这些不可能是 ref）
+ * 静态分析能明确变量类型时，跳过 unref 包装以提升性能
  * @param program - AST Program 节点
  * @returns 非 ref 变量名集合
  */

package/dist/passes/imports/collectRefVariables.js

@@ -1,5 +1,5 @@
 import { REF_APIS, RESPONSIVE_MODULES } from '../../constants/index.js';
-import { collectPatternBindings, collectObjectPatternBindings } from '../../utils/index.js';
+import { collectObjectPatternBindings, collectPatternBindings } from '../../utils/index.js';
 /**
  * 收集 ref API 的别名
  * 识别从 vitarx 或 @vitarx/responsive 导入的 ref/toRef/toRefs/shallowRef/computed
@@ -76,6 +76,15 @@ function collectRefVariablesFromNode(node, refVariables, refApiLocalNames, toRef
             if (decl.id.type === 'VoidPattern')
                 continue;
             const init = decl.init;
+            // 如果 init 是箭头函数或函数表达式，递归处理其函数体内的 ref 声明
+            // 确保组件函数（如 const App = () => { const count = ref(0) }）内的 ref 被正确收集
+            if ((init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') &&
+                init.body.type === 'BlockStatement') {
+                for (const stmt of init.body.body) {
+                    collectRefVariablesFromNode(stmt, refVariables, refApiLocalNames, toRefsLocalNames);
+                }
+                continue;
+            }
             // 检查是否为函数调用表达式
             if (init.type !== 'CallExpression' || init.callee.type !== 'Identifier') {
                 continue;
@@ -102,24 +111,32 @@ function collectRefVariablesFromNode(node, refVariables, refApiLocalNames, toRef
         collectRefVariablesFromNode(node.declaration, refVariables, refApiLocalNames, toRefsLocalNames);
     }
     else if (node.type === 'ExportDefaultDeclaration') {
-        // 处理默认导出
+        // 处理默认导出（支持函数声明、箭头函数、函数表达式）
         const decl = node.declaration;
         if (decl.type === 'FunctionDeclaration' && decl.body) {
             for (const stmt of decl.body.body) {
                 collectRefVariablesFromNode(stmt, refVariables, refApiLocalNames, toRefsLocalNames);
             }
         }
+        else if ((decl.type === 'ArrowFunctionExpression' || decl.type === 'FunctionExpression') &&
+            decl.body.type === 'BlockStatement') {
+            for (const stmt of decl.body.body) {
+                collectRefVariablesFromNode(stmt, refVariables, refApiLocalNames, toRefsLocalNames);
+            }
+        }
     }
+    // 控制流语句（if/for/while/switch/try）中的变量声明不递归收集
+    // 函数控制流中通常不会声明 ref 变量，仅收集模块顶层和函数体顶层
 }
 /**
  * 收集确定不是 ref 的变量
  * 包括函数声明、箭头函数和函数表达式变量（这些不可能是 ref）
+ * 静态分析能明确变量类型时，跳过 unref 包装以提升性能
  * @param program - AST Program 节点
  * @returns 非 ref 变量名集合
  */
 export function collectNonRefVariables(program) {
     const nonRefVariables = new Set();
-    // 遍历程序体中的所有节点
     for (const node of program.body) {
         collectNonRefFromNode(node, nonRefVariables);
     }
@@ -127,6 +144,7 @@ export function collectNonRefVariables(program) {
 }
 /**
  * 从节点中递归收集非 ref 变量
+ * 仅处理模块顶层和函数体顶层的声明，不递归控制流语句
  * @param node - AST 节点
  * @param nonRefVariables - 存储非 ref 变量名的集合
  */
@@ -134,7 +152,6 @@ function collectNonRefFromNode(node, nonRefVariables) {
     // 函数声明一定不是 ref
     if (node.type === 'FunctionDeclaration' && node.id) {
         nonRefVariables.add(node.id.name);
-        // 递归处理函数体内的变量
         if (node.body) {
             for (const stmt of node.body.body) {
                 collectNonRefFromNode(stmt, nonRefVariables);
@@ -142,33 +159,49 @@ function collectNonRefFromNode(node, nonRefVariables) {
         }
     }
     else if (node.type === 'VariableDeclaration') {
-        // 变量声明：只有箭头函数或函数表达式才是非 ref
+        // 变量声明：箭头函数或函数表达式赋值一定不是 ref
         for (const decl of node.declarations) {
             if (!decl.init)
                 continue;
-            // 只处理简单标识符（不处理解构）
-            if (decl.id.type !== 'Identifier')
-                continue;
             const init = decl.init;
-            if (init.type === 'ArrowFunctionExpression' ||
-                init.type === 'FunctionExpression') {
-                nonRefVariables.add(decl.id.name);
+            if (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') {
+                if (decl.id.type === 'Identifier') {
+                    nonRefVariables.add(decl.id.name);
+                }
+                // 递归处理函数体内的变量声明
+                if (init.body.type === 'BlockStatement') {
+                    for (const stmt of init.body.body) {
+                        collectNonRefFromNode(stmt, nonRefVariables);
+                    }
+                }
             }
         }
     }
-    else if (node.type === 'ExportNamedDeclaration') {
-        // 处理命名导出的声明
-        if (node.declaration) {
-            collectNonRefFromNode(node.declaration, nonRefVariables);
-        }
+    else if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+        collectNonRefFromNode(node.declaration, nonRefVariables);
     }
     else if (node.type === 'ExportDefaultDeclaration') {
-        // 处理默认导出
         const decl = node.declaration;
-        if (decl.type === 'FunctionDeclaration' && decl.id) {
-            nonRefVariables.add(decl.id.name);
+        if (decl.type === 'FunctionDeclaration') {
+            if (decl.id) {
+                nonRefVariables.add(decl.id.name);
+            }
+            // 递归处理函数体，收集内部非 ref 变量（与 collectRefVariablesFromNode 一致）
+            if (decl.body) {
+                for (const stmt of decl.body.body) {
+                    collectNonRefFromNode(stmt, nonRefVariables);
+                }
+            }
+        }
+        else if ((decl.type === 'ArrowFunctionExpression' || decl.type === 'FunctionExpression') &&
+            decl.body.type === 'BlockStatement') {
+            // 处理未被转换的箭头函数/函数表达式默认导出
+            for (const stmt of decl.body.body) {
+                collectNonRefFromNode(stmt, nonRefVariables);
+            }
         }
     }
+    // 控制流语句（if/for/while/switch/try）中的变量声明不递归收集
 }
 /**
  * 构建 ref API 的本地名称集合

package/dist/passes/jsx/processJSXFragment.js

@@ -1,7 +1,24 @@
 import * as t from '@babel/types';
+import { isJSXElement } from '@babel/types';
 import { markImport } from '../../context.js';
-import { addPureComment, createCreateViewCall, filterWhitespaceChildren, getAlias, getDevLocInfo, validateNoDirectMatchChild } from '../../utils/index.js';
+import { createError } from '../../error.js';
+import { addPureComment, createCreateViewCall, filterWhitespaceChildren, getAlias, getDevLocInfo, getJSXElementName } from '../../utils/index.js';
 import { processChildren } from './processChildren.js';
+/**
+ * 校验子节点中不能直接包含 Match 组件
+ * Match 必须在 Switch 内使用，非 Switch 元素的子节点中不允许出现 Match
+ * @param children - 子节点数组
+ */
+function validateNoDirectMatchChild(children) {
+    for (const child of children) {
+        if (isJSXElement(child)) {
+            const childName = getJSXElementName(child);
+            if (childName === 'Match') {
+                throw createError('E012', child);
+            }
+        }
+    }
+}
 /**
  * 处理 JSX Fragment
  * @param path - JSX Fragment 路径

package/dist/passes/props/attribute.d.ts

@@ -32,6 +32,9 @@ export declare function getAttributeValue(value: t.JSXAttribute['value']): t.Exp
  *
  * 特殊处理：
  * - children 属性不使用 unref，因为 ref 作为 children 是合法的可变渲染源
+ * - ref 属性不使用 unref/.value，因为 ref 绑定需要 ref 对象本身
+ *   运行时 resolveProps() 通过 isRef() 判定 ref 属性值，若此处解包，
+ *   popProperty 取到的是解包后的值（如 null），isRef 判定失败导致绑定失效
  * - 其他标识符属性使用 unref 解包
  *
  * @param key - 属性名

package/dist/passes/props/attribute.js

@@ -87,6 +87,9 @@ export function getAttributeValue(value) {
  *
  * 特殊处理：
  * - children 属性不使用 unref，因为 ref 作为 children 是合法的可变渲染源
+ * - ref 属性不使用 unref/.value，因为 ref 绑定需要 ref 对象本身
+ *   运行时 resolveProps() 通过 isRef() 判定 ref 属性值，若此处解包，
+ *   popProperty 取到的是解包后的值（如 null），isRef 判定失败导致绑定失效
  * - 其他标识符属性使用 unref 解包
  *
  * @param key - 属性名
@@ -107,15 +110,22 @@ ctx // 转换上下文，包含转换过程中的相关信息
     }
     // 如果是标识符（变量名）
     if (t.isIdentifier(value)) {
-        // 特殊处理 children 属性或不在 refVariables 中的变量
-        if (key === 'children' || ctx.nonRefVariables.has(value.name)) {
+        // 特殊处理 children 和 ref 属性：
+        // - children: ref 作为 children 是合法的可变渲染源，需保持引用本身
+        // - ref: ref 绑定需要 ref 对象本身，运行时通过 isRef() 判定后赋值 .value
+        //   若此处 unref/.value 解包，popProperty 取到解包值（如 null），isRef 失败
+        if (key === 'children' || key === 'ref') {
+            return t.objectProperty(keyNode, value);
+        }
+        // 已知非 ref 变量（函数声明、箭头函数等）：静态分析确定非 ref，直接赋值无需 unref
+        if (ctx.nonRefVariables.has(value.name)) {
             return t.objectProperty(keyNode, value);
         }
         // 如果是 ref 变量，创建 getter 方法返回 ref 的 value
         if (ctx.refVariables.has(value.name)) {
             return createGetter(keyNode, t.returnStatement(t.memberExpression(value, t.identifier('value'))));
         }
-        // 其他标识符属性创建 unref getter
+        // 未知标识符：创建 unref getter（非 ref 原样返回，安全）
         return createUnrefGetter(keyNode, value, ctx);
     }
     // 如果是成员表达式（如 obj.property）

package/dist/transform.js

@@ -64,12 +64,13 @@ function setupAliases(ctx, program) {
 }
 /**
  * 收集 ref 相关信息
+ * 注意：nonRefVariables 在 collectComponentFunctions 之后单独收集，
+ * 因为匿名默认导出需要先被转换为命名函数才能被识别
  */
 function collectRefInfo(ctx, program) {
     const refApiAliases = collectRefApiAliases(program);
     ctx.refApiAliases = refApiAliases;
     ctx.refVariables = collectRefVariables(program, refApiAliases);
-    ctx.nonRefVariables = collectNonRefVariables(program);
 }
 /**
  * 转换 AST
@@ -146,6 +147,9 @@ export async function transform(code, id, options) {
     setupAliases(ctx, ast.program);
     collectRefInfo(ctx, ast.program);
     const components = collectComponentFunctions(ast.program, ctx.builderAlias);
+    // 在组件函数收集之后收集非 ref 变量
+    // 此时匿名默认导出已被转换为命名函数，可被正确识别为非 ref
+    ctx.nonRefVariables = collectNonRefVariables(ast.program);
     transformAST(ast, ctx);
     injectImports(ast.program, ctx);
     if (options.hmr && components.length > 0 && !isEntryFile(id)) {

package/dist/types.d.ts

@@ -53,7 +53,7 @@ declare global {
              *
              * ```tsx
              * const show = ref(true)
-             * // v-if指令不支持 ref 自动解包，必须使用.value
+             * // v-if 指令支持 ref 自动解包，ref.value 是可选的
              * <div v-if={show.value}></div>
              * ```
              */

package/dist/utils/branch-factory.js

@@ -16,9 +16,7 @@ import { addPureComment, createArrowFunction, createBranchCall, createUnrefCall,
 export function createBranch(config, ctx) {
     const { conditions, branches, useRef = true } = config;
     markImport(ctx, 'branch');
-    if (useRef && conditions.some(c => isIdentifier(c) && ctx.refVariables.has(c.name))) {
-        markImport(ctx, 'unref');
-    }
+    // unref 导入标记由 buildNestedCondition 内部统一管理
     const conditionExpr = buildNestedCondition(conditions, ctx, useRef);
     const branchAlias = getAlias(ctx.vitarxAliases, 'branch');
     return addPureComment(createBranchCall(createArrowFunction(conditionExpr), branches, branchAlias), ctx);
@@ -63,8 +61,28 @@ export function buildNestedCondition(conditions, ctx, useRef = true) {
             result = t.numericLiteral(i);
             continue;
         }
-        // 构建条件表达式
-        const conditionExpr = useRef && isIdentifier(condition) ? createUnrefCall(condition, unrefAlias) : condition;
+        // 构建条件表达式：对标识符进行三态解包
+        // 已知 ref → .value（高效），已知非 ref → 原样（静态分析确定），未知 → unref()（安全）
+        let conditionExpr;
+        if (useRef && isIdentifier(condition)) {
+            if (ctx.refVariables.has(condition.name)) {
+                // 已知 ref：直接使用 .value
+                conditionExpr = t.memberExpression(condition, t.identifier('value'));
+            }
+            else if (ctx.nonRefVariables.has(condition.name)) {
+                // 已知非 ref（函数等）：原样使用，无需解包
+                conditionExpr = condition;
+            }
+            else {
+                // 未知标识符：使用 unref() 解包（非 ref 原样返回）
+                markImport(ctx, 'unref');
+                conditionExpr = createUnrefCall(condition, unrefAlias);
+            }
+        }
+        else {
+            // 复杂表达式：原样不解包，用户手动写 .value
+            conditionExpr = condition;
+        }
         // 对复杂条件表达式添加括号
         const wrappedCondition = wrapExpression(conditionExpr);
         if (result === null) {
@@ -89,6 +107,8 @@ export function buildNestedCondition(conditions, ctx, useRef = true) {
 export function createBinaryBranch(condition, consequent, alternate, ctx) {
     const conditions = [condition, t.booleanLiteral(true)];
     const branches = [createArrowFunction(consequent), createArrowFunction(alternate)];
-    const useRef = isIdentifier(condition);
+    // 三元表达式不解包 ref，用户需手动写 .value
+    // 这样 TypeScript 类型推导能正确检查 Ref<T> 参与运算的类型错误
+    const useRef = false;
     return createBranch({ conditions, branches, useRef }, ctx);
 }

package/dist/utils/component-collect.d.ts

@@ -14,6 +14,13 @@ export interface ComponentInfo {
     /** 是否为包装组件（传递给 builder 函数） */
     isWrapped?: boolean;
 }
+/**
+ * 检查名称是否为有效的组件名称
+ * 必须以大写字母开头（符合 React/Vue 组件命名规范）
+ * @param name - 待检查的名称
+ * @returns 是否为有效组件名称
+ */
+export declare function isValidComponentName(name: string): boolean;
 /**
  * 收集模块中的组件函数
  * 遍历 AST 程序节点，提取所有导出的组件函数