weapp-vite-vue-sfc-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

weapp-vite-vue-sfc-best-practices

weapp-vite-vue-sfc最佳实践

Purpose

目的

Implement Vue SFC for mini-programs with a two-layer model: compile-time rules (weapp-vite) and runtime behavior (wevu). Favor predictable compile output and explicit mini-program semantics.

通过两层模型实现小程序的Vue SFC能力：编译层规则（weapp-vite）和运行层行为（wevu），优先保证可预测的编译输出和明确的小程序语义。

Trigger Signals

触发信号

User asks how to write/refactor mini-program
```
.vue
```
files.

User asks about JSON macro usage (

definePageJson

defineComponentJson

defineAppJson

) or

<json>

migration.

User hits directive compatibility issues (
```
v-model
```
assignment rules,
```
v-bind="object"
```
behavior).
User reports SFC compile or runtime mismatch after template/script changes.
User asks how to declare
```
usingComponents
```
correctly in SFC.

用户询问如何编写/重构小程序
```
.vue
```
文件
用户询问JSON宏（
```
definePageJson
```
、
```
defineComponentJson
```
、
```
defineAppJson
```
）用法或
```
<json>
```
标签迁移问题
用户遇到指令兼容性问题（
```
v-model
```
赋值规则、
```
v-bind="object"
```
行为表现）
用户反馈修改模板/脚本后出现SFC编译或运行时表现不匹配的问题
用户询问如何在SFC中正确声明
```
usingComponents
```

Scope Boundary

适用边界

Use this skill when the center of gravity is SFC authoring and compile compatibility.

Do not use this as the primary skill when:

The issue is mostly project-level build/CI/subpackage strategy. Use
```
weapp-vite-best-practices
```
.
The issue is mostly runtime lifecycle/store/event architecture. Use
```
wevu-best-practices
```
.
The task is phased migration from native mini-program. Use
```
native-to-weapp-vite-wevu-migration
```
.

当问题核心是SFC编写和编译兼容性时使用本指南。

以下场景不建议将本指南作为首选参考：

问题以项目级构建/CI/分包策略为主，请参考
```
weapp-vite-best-practices
```
问题以运行时生命周期/状态管理/事件架构为主，请参考
```
wevu-best-practices
```
任务是原生小程序分阶段迁移，请参考
```
native-to-weapp-vite-wevu-migration
```

Quick Start

快速开始

Confirm SFC type first: App, Page, or Component.
Pick one JSON macro family that matches the SFC role.
Validate template directives against mini-program compatibility constraints.
Verify runtime API imports and hook timing.

首先确认SFC类型：App、Page还是Component
选择与SFC角色匹配的JSON宏系列
根据小程序兼容性约束校验模板指令
验证运行时API导入和钩子执行时机

Execution Protocol

执行规范

Classify the failure stage

Compile-time: macro syntax, template transform,
```
usingComponents
```
declaration.
Runtime: hook timing, event payload, reactive update expectations.
Tooling/type: Volar config,
```
vueCompilerOptions.lib
```
, type resolution.

Enforce SFC boundaries

Keep
```
<template>/<script>/<style>
```
responsibilities explicit.
Manage mini-program JSON via Script Setup JSON macros first.
Use
```
<json>
```
only for legacy compatibility or explicit migration constraints.
Do not register mini-program components via script-side ESM registration patterns.

Apply script rules

Prefer
```
<script setup lang="ts">
```
.
Import runtime APIs from
```
wevu
```
in business logic.
Register hooks synchronously in
```
setup()
```
and avoid post-
```
await
```
registration.

Apply macro and template rules

Use only one macro family per SFC.

App ->

defineAppJson

; Page ->

definePageJson

; Component ->

defineComponentJson

Keep macro calls top-level with a single object argument.
For
```
v-model
```
, only use assignable left values:
```
x
```
,
```
x.y
```
,
```
x[i]
```
.
Avoid unsupported forms such as
```
v-model
```
modifiers/arguments and full-object
```
v-bind
```
expansion assumptions.

Verify narrowly

Run targeted checks that match the touched SFC files.
Escalate to broader runs only when cross-page behavior is affected.

归类问题出现阶段

编译期：宏语法、模板转换、
```
usingComponents
```
声明问题
运行期：钩子时机、事件载荷、响应式更新预期不符问题
工具/类型问题：Volar配置、
```
vueCompilerOptions.lib
```
、类型解析问题

严格遵守SFC职责边界

明确划分
```
<template>/<script>/<style>
```
的职责
优先通过Script Setup的JSON宏管理小程序JSON配置
仅当存在旧版兼容需求或明确迁移限制时才使用
```
<json>
```
标签
不要通过脚本侧ESM注册模式注册小程序组件

脚本编写规则

优先使用
```
<script setup lang="ts">
```
业务逻辑中从
```
wevu
```
导入运行时API
在
```
setup()
```
中同步注册钩子，避免在
```
await
```
之后注册

宏和模板编写规则

每个SFC仅使用一个系列的宏

App ->

defineAppJson

；Page ->

definePageJson

；Component ->

defineComponentJson

宏调用需放在顶层，仅传入单个对象参数
对于
```
v-model
```
，仅使用可赋值的左值：
```
x
```
、
```
x.y
```
、
```
x[i]
```
避免使用不支持的形式，例如
```
v-model
```
修饰符/参数，以及全对象
```
v-bind
```
展开的默认行为假设

针对性验证

针对修改过的SFC文件执行定向检查
仅当跨页面行为受影响时再扩大验证范围

Guardrails

注意事项

Do not treat mini-program component registration like web Vue component registration.
Do not register hooks after
```
await
```
in
```
setup()
```
.
Do not assume web Vue template features are fully available in mini-program compilation.
Do not mix multiple JSON macro families in one SFC.
Do not mix SFC syntax fixes with unrelated runtime architecture refactors.

不要将小程序组件注册和Web Vue组件注册的方式等同
不要在
```
setup()
```
的
```
await
```
之后注册钩子
不要默认认为Web Vue的模板特性在小程序编译环境下完全可用
不要在单个SFC中混合使用多个系列的JSON宏
不要将SFC语法修复和无关的运行时架构重构混合进行

Output Contract

输出约定

When applying this skill, return:

Stage-based diagnosis (compile/runtime/tooling).
Concrete SFC-level edit list.
Compatibility notes for directives/macros used.
Minimal verification commands.

应用本指南时，需返回以下内容：

按阶段给出的问题诊断（编译/运行/工具侧）
具体的SFC级别的修改清单
所使用的指令/宏的兼容性说明
最简验证命令

Completion Checklist

完成检查清单

SFC config path is clear and macro-first (avoid new
```
<json>
```
usage by default).
```
usingComponents
```
strategy is deterministic and path-safe.
Template usage avoids unsupported directive forms.
Runtime API imports come from
```
wevu
```
.
Hook timing and page/component context are valid.

SFC配置路径清晰，优先使用宏（默认避免新增
```
<json>
```
用法）
```
usingComponents
```
策略可确定，路径安全
模板使用避免了不支持的指令形式
运行时API从
```
wevu
```
导入
钩子执行时机和页面/组件上下文有效

References

参考资料

```
references/macro-config-checklist.md
```
```
references/template-compat-matrix.md
```
```
references/troubleshooting-playbook.md
```

```
references/macro-config-checklist.md
```
```
references/template-compat-matrix.md
```
```
references/troubleshooting-playbook.md
```