weapp-vite-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

weapp-vite-best-practices

weapp-vite最佳实践

Overview

概述

Build and maintain weapp-vite projects with stable conventions first, then tune performance and build behavior. Prefer minimal config that matches project structure.

首先以稳定的规范构建和维护weapp-vite项目，然后再优化性能和构建行为。优先选择与项目结构匹配的极简配置。

Workflow

工作流

Confirm baseline

Use Node
```
^20.19.0 || >=22.12.0
```
and consistent pnpm.
Ensure WeChat DevTools service port is enabled before using
```
--open
```
workflows.
Verify
```
weapp.srcRoot
```
matches real source root (
```
src
```
or
```
miniprogram
```
).

Define project structure

Keep pages under
```
src/pages/**
```
and subpackages under
```
src/packages/**
```
.
Keep reusable components in
```
src/components/**
```
and shared logic in
```
src/shared/**
```
or
```
src/utils/**
```
.
Prefer explicit config layering: Vite in
```
vite.config.ts
```
, mini-program specifics in
```
weapp
```
field.

Apply high-value defaults

Enable
```
weapp.autoRoutes
```
when using convention-based pages.
Keep auto component import on by default; only add custom
```
globs/resolvers
```
when needed.
Use Script Setup JSON macros for App/Page/Component config instead of scattered manual JSON edits.

Prefer matching JSON macros by file type:

defineAppJson

definePageJson

defineComponentJson

Keep
```
<json>
```
only for legacy compatibility.

Choose subpackage strategy intentionally

Use normal subpackages for shared build context.
Use independent subpackages only when strict isolation is needed.
Choose
```
weapp.chunks.sharedStrategy
```
by goal:
- ```
duplicate
```
  : better subpackage first-open experience.
- ```
hoist
```
  : better total package deduplication/control.

Keep build and CI deterministic

Use stable scripts (
```
dev
```
,
```
build
```
,
```
open
```
, optional
```
analyze
```
).
In CI, separate compile and IDE/preview/upload steps.
For CLI automation, prefer
```
weapp-ide-cli
```
and non-interactive mode.

Debug with framework hooks

Use
```
weapp.debug.watchFiles/resolveId/load
```
for missing output and resolution issues.
Use
```
inspect
```
(plugin hook timings) for slow build diagnosis.
Validate route/component generation artifacts (
```
typed-router.d.ts
```
, auto import outputs).

确认基准环境

使用 Node
```
^20.19.0 || >=22.12.0
```
版本和统一的 pnpm 包管理器。
在使用
```
--open
```
工作流前，确保微信开发者工具的服务端口已启用。
验证
```
weapp.srcRoot
```
配置与实际源码根目录（
```
src
```
或
```
miniprogram
```
）一致。

定义项目结构

将页面文件放在
```
src/pages/**
```
目录下，分包文件放在
```
src/packages/**
```
目录下。
将可复用组件放在
```
src/components/**
```
目录下，共享逻辑放在
```
src/shared/**
```
或
```
src/utils/**
```
目录下。
优先采用明确的配置分层：Vite配置写在
```
vite.config.ts
```
中，小程序专属配置放在
```
weapp
```
字段中。

应用高价值默认配置

当采用约定式页面结构时，启用
```
weapp.autoRoutes
```
配置。
保持自动组件导入默认开启；仅在需要时添加自定义
```
globs/resolvers
```
。
使用Script Setup JSON宏定义App/Page/Component配置，替代分散的手动JSON编辑。
根据文件类型匹配对应的JSON宏：
```
defineAppJson
```
/
```
definePageJson
```
/
```
defineComponentJson
```
。
仅在兼容旧代码时保留纯
```
<json>
```
文件。

谨慎选择分包策略

对于共享构建上下文的场景，使用普通分包。
仅在需要严格隔离的场景下使用独立分包。
根据目标选择
```
weapp.chunks.sharedStrategy
```
：
- ```
duplicate
```
  ：优化分包首次打开体验。
- ```
hoist
```
  ：优化整体包体积去重与管控。

确保构建与CI的确定性

使用稳定的脚本命令（
```
dev
```
、
```
build
```
、
```
open
```
，可选
```
analyze
```
）。
在CI流程中，分离编译步骤与IDE预览/上传步骤。
对于CLI自动化，优先使用
```
weapp-ide-cli
```
和非交互模式。

借助框架钩子调试

当遇到输出缺失或解析问题时，使用
```
weapp.debug.watchFiles/resolveId/load
```
进行调试。
当构建缓慢时，使用
```
inspect
```
（插件钩子计时）诊断问题。
验证路由/组件生成的产物（
```
typed-router.d.ts
```
、自动导入输出结果）。

Guardrails

注意事项

Avoid customizing config before confirming
```
srcRoot
```
and output roots are correct.
Avoid mixing many advanced chunk overrides early; start from default strategy and add targeted rules.
Avoid treating mini-program config as web-only conventions; keep
```
usingComponents
```
, subpackage roots, and JSON semantics explicit.

在确认
```
srcRoot
```
和输出根目录配置正确前，避免自定义其他配置。
初期避免混合使用过多高级代码分割覆盖规则；从默认策略开始，逐步添加针对性规则。
不要将小程序配置视为纯Web约定；保持
```
usingComponents
```
、分包根目录和JSON语义的明确性。

Completion Checklist

完成检查清单

```
vite.config.ts
```
has clear
```
weapp
```
section with minimal required options.
```
pages/subPackages
```
source-of-truth strategy is clear (manual or auto routes).
Component registration strategy is consistent (auto import + resolver policy documented).
Subpackage/chunk strategy is chosen and justified.
Dev/CI workflow is repeatable and does not depend on manual IDE steps.

```
vite.config.ts
```
中有清晰的
```
weapp
```
配置段，仅包含必要的最少选项。
```
pages/subPackages
```
的数据源策略明确（手动配置或自动路由）。
组件注册策略一致（自动导入 + 解析器策略已文档化）。
已选择并论证分包/代码分割策略的合理性。
开发/CI工作流可重复，不依赖手动IDE操作。

References

参考资料

```
references/config-playbook.md
```
```
references/debug-playbook.md
```

```
references/config-playbook.md
```
```
references/debug-playbook.md
```