错误码参考

Qingkuai 的编译器和运行时可能会抛出附带错误码的诊断信息，帮助开发者快速定位问题。本节列出当前版本内置错误码及其含义，便于查阅与排查。错误码按功能类型分类，编号规则如下：

通过错误码快速查找具体信息，可提升排错效率并更好地理解框架的行为。

编译错误

错误码 描述
1001 空插值块
1002 意料之外的字符
1003 未闭合的插值块
1004 以结束标签开头（如 </div> 前不存在与之匹配的 <div>）
1005 插值属性缺少名称（如仅写 !、@、# 或 &）
1006 静态属性值未使用单引号或双引号包裹
1007 插值属性值未使用花括号包裹
1008 静态属性值未闭合
1009 标签未闭合（包括开始标签、结束标签或注释标签）
1010 嵌入语言标签未在模板顶层使用
1011 嵌入脚本块超出限制（组件文件最多一个）
1012 标签缺少匹配的结束标签
1013 标签不能作为自闭合标签使用（如 <div />）
1014 使用了组件文件中不允许的标签
1015 模板结构非法（如 <div> 嵌套在 <p> 内）
1016 属性格式非法
1017 使用了框架保留的标识符格式（以 __qk__ 开头的标识符）
1018 不支持的顶层 await 表达式
1019 嵌入脚本块中不支持以下导出形式：export =、默认导出、再导出、命名空间导出、类型导出
1020 顶级作用域中重定义内建标识符
1021 内建方法使用位置或调用形式错误
1022 标识符不可重声明（与别名或衍生值标记冲突）
1023 defaults 内建方法在嵌入脚本块中只能调用一次
1024 alias 内建方法参数非法（必须且只能传入一个可写目标）
1025 alias 解构声明中包含不允许的模式
1026 指令冲突（不能在同一标签上共存）
1027 指令缺少必要的值
1028 属性重复或解析后冲突（含静态/动态/事件/引用属性冲突）
1029 表达式非法
1030 标签不接受当前属性类型（如错误的引用属性或事件属性）
1031 缺少前置指令（如 #elif、#else、#then、#catch 等）
1032 上下文模式（context pattern）非法
1033 未识别的指令
1034 上下文模式为空（未声明任何绑定标识符）
1035 #html 指令的标签必须且只能有一个文本子节点
1036 #slot 指令使用位置非法（仅允许组件节点的一级子元素）
1037 指令解构绑定模式数量超限（如 #for、#then 等）
1038 #slot 指令缺少合法插槽名（from 后必须为字符串字面量）
1039 <slot> 标签的 name 属性必须是静态值
1040 #target 指令使用位置非法（组件一级子元素上会导致目标歧义）
1041 期望表达式
1042 期望字符串字面量
1043 #key 指令只能与 #for 同时使用
1044 期望事件标志名
1045 未识别的事件标志
1046 事件标志冲突
1047 标签上的引用属性不合法（不在允许列表内）
1048 引用属性值非法（必须是标识符或成员表达式）
1049 省略写法的特殊属性名非法（无法转换为合法标识符）
1050 <slot> 的 name 属性重复
1051 同一组件内重复分配到同名插槽
1052 嵌入脚本块不支持 TypeScript 命名空间声明
1053 alias 不能用于独立标识符别名化
1054 内建方法不能用于 using / await using 声明
1055 不允许嵌套 <slot>
1056 Promise 块中 #then 或 #catch 指令重复
1057 组件名称非法（无法转换为合法 JS 标识符或成员表达式）
1058 #html 指令不能用于组件或 <slot> 标签
1059 指定内建方法不支持扩展参数（spread element）
1060 元素标签名非法
1061 内建方法不能在模板中使用
1062 响应式模式冲突（同一标签同时声明 reactive 与 shallow）
1063 组件标签上的泛型参数未闭合
1064 组件标签泛型参数只能在嵌入脚本类型为 TypeScript 时使用
1065 成员表达式形式的组件标签不允许使用连字符
1066 自闭合嵌入样式标签必须提供 src 属性
1067 带 src 属性的嵌入样式标签不能包含内联样式内容
1068 嵌入样式标签上的 src 属性值不能为空
1069 #scope 指令只能用于组件上
1070 禁用 allowConstReactive 编译选项时，不允许用 reactive/shallow 标记 const 声明
1071 raw 用作非响应式读取时必须传递参数
1072 raw 用作非响应式读取时只能传递一个参数
1073 raw 用作非响应式读取时必须用作函数调用
1074 编译选项 requireReactivityMark 为 true 时顶层变量声明必须使用响应性内建方法显式标记

编译警告

错误码 描述
9001 值恒定不变，响应式标记冗余（将按原始值处理）
9002 顶级作用域标识符在特定作用域中可能被覆盖
9003 #scope 指令在当前组件没有作用域样式时无效
9004 衍生响应式值为只读，使用可变声明冗余（建议改为 const）
9005 对字面量 const 进行 raw 标记是冗余的
9006 指令不需要值，提供的值会被忽略
9007 布尔属性提供了冗余值，冗余值会被忽略
9008 #html 指令在无值且静态内容场景下无实际作用
9009 组件事件监听器上的事件标志无效，会被忽略
9010 在非键盘事件上使用键盘事件标志无效，会被忽略
9011 事件标志重复，重复项会被忽略
9012 缺少必要属性（如动态属性、引用属性或事件监听器）的 qk:spread 标签是冗余的
9013 #scope 指令在此处不必要，因为该组件已有实际祖先元素
9014 嵌套的 raw 调用冗余，参数已是非响应式读取，内层 raw 会被忽略
9015 未加 #key 的 #for 列表项含有内部状态，列表更新时可能串位

运行时错误

错误码 描述
2001 指定用途（如 #await）收到的值不是 Promise
2002 #for 指令值不可遍历
2003 #key 指令值存在重复项
2004 超出最大递归更新深度（常见于异步副作用/监视器中的递归更新）
2005 目标元素无效（不是合法 Element，或无法通过选择器获取）
2006 &group 或多选 <select> 的 &value 属性值必须是数组或集合
2007 无法渲染组件：给定值既不是组件函数，也不是解析为组件函数的 Promise

运行时警告

错误码 描述
8001 执行副作用/监视器时未收集到任何响应式依赖，该副作用会被销毁
8002 对只读或无效目标执行赋值操作，赋值会被忽略
8003 所属组件销毁后仍尝试创建内容（常见于组件移除后异步回调才执行创建子组件或注册监视器/副作用），该创建已被忽略
8004 生命周期方法在对应阶段已过后仍被注册（如挂载后在异步回调中注册 onAfterMount），回调永远不会触发，该注册已被忽略

语言服务错误

错误码 描述
3001 组件契约类型 Meta 声明了未知成员（仅允许 props、refs、contexts）
3002 (TypeScript) Meta 类型或其成员不是对象类型（如基本类型、联合类型等）
3003 依赖 "qingkuai" 未找到，请确保已安装且可解析
3004 外部导入的类型携带泛型参数，不能直接作为契约类型 Meta 使用
3005 组件不允许导出类型，请将类型移到外部 .ts 文件中再导入

语言服务警告

错误码 描述
7001 (JavaScript) 通过 JSDoc 声明的 Meta 类型或其成员不是对象类型（如基本类型、联合类型等）
7002 @keyframes 规则不会被添加作用域，建议定义在外部样式表中并从应用入口文件导入

在github上编辑此页面