目录结构

这一组文档按“目录即能力边界”的方式组织，交互形态参考 Nuxt 的 directory structure 页面。

• 左侧每一个目录或文件项，都是单独的文档路由
• 右侧页面只解释当前项的职责、默认行为和触发的能力
• 如果你只想先看全局，再决定点进哪个目录，从这页开始就够了

一个典型项目

.
├─ vite.config.ts
├─ project.config.json
├─ package.json
├─ public/
└─ <srcRoot>/
   ├─ app.(js|ts)
   ├─ app.vue
   ├─ app.json(.js|.ts)?
   ├─ app.(css|scss|wxss|...)
   ├─ custom-tab-bar/
   ├─ app-bar/
   ├─ pages/
   ├─ components/
   ├─ <subPackageRoot>/
   │  ├─ pages/
   │  └─ components/
   ├─ shared/
   ├─ utils/
   ├─ workers/
   ├─ typed-router.d.ts
   ├─ typed-components.d.ts
   └─ components.d.ts

先记住三条

1. weapp-vite 真正依赖的是 srcRoot，不是硬编码的 src/
2. 页面自动扫描默认只看 srcRoot/pages/** 和已声明分包 root 下的 pages/**
3. custom-tab-bar、app-bar、类型声明文件这些都属于带固定语义的保留位置

TIP

这一组文档里的 <srcRoot>、<subPackageRoot> 都是变量占位，不是固定目录名。它们分别代表你在 vite.config.ts 中声明的源码根目录和分包 root。

Root Directory

先看工程入口。这里决定项目如何被开发者工具、VitePress 和 Weapp-vite 自身识别。

vite.config.ts

定义 srcRoot、自动路由、分包和自动导入组件等目录能力。

project.config.json

微信开发者工具项目配置，通常决定 dist 的打开方式。

package.json

项目脚本与依赖入口，承载 dev、build、open 等命令。

public/

原样复制到产物目录的静态资源，不参与页面扫描。

App Directory

再看源码根目录。这里既承接应用入口，也定义页面、组件、分包与特殊固定目录的边界。

<srcRoot>/

所有 pages、components、分包和生成类型文件都基于它定位。

app.(js|ts)

应用脚本入口，承载 App 生命周期、启动逻辑和全局初始化。

app.vue

Vue SFC 形式的应用入口，可在同一文件中组织脚本、JSON 宏与样式。

app.json(.js|.ts)?

应用配置入口，既支持原生 JSON，也支持脚本化生成配置。

app.(css|scss|wxss|...)

应用级全局样式入口，支持 CSS、WXSS 及常见预处理器后缀。

custom-tab-bar/

tabBar.custom 为 true 时的固定保留目录。

app-bar/

Skyline appBar 开启时的固定保留目录。

pages/

主包页面目录，也是自动路由的默认扫描入口之一。

components/

主包组件目录，默认参与自动导入组件扫描。

<subPackageRoot>/

通过 weapp.subPackages 声明的分包根目录。

shared/

跨主包与分包共享模块的推荐目录。

utils/

通用工具函数和轻量 helper 的稳定落点。

workers/

Worker 入口的推荐目录。

Generated Files

最后看自动生成产物。它们默认也落在 srcRoot 下，方便 tsconfig 直接覆盖。

typed-router.d.ts / typed-components.d.ts / components.d.ts

自动路由和自动导入组件生成的类型声明文件集合。

从哪里开始看

• 想先建立全局认知：看 📄 vite.config.ts、📁 <srcRoot>/
• 想搞清楚页面与分包：看 📁 <srcRoot>/pages/、📁 <srcRoot>/<subPackageRoot>/
• 想搞清楚自动生成产物：看 类型声明文件

默认能力速查

| 位置 | 作用 | | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------- | ----- | ------------------------------------------- | | vite.config.ts | 定义 srcRoot、自动路由、分包、自动导入组件等能力 | | project.config.json | 微信开发者工具配置 | | public/ | 构建时原样复制的静态资源 | | app.(js | ts) | 应用脚本入口，承载生命周期和全局初始化 | | app.vue | Vue SFC 形式的应用入口，可组合脚本、JSON 宏与样式 | | app.json(.js | .ts)? | 应用配置入口，既支持原生 JSON，也支持脚本化生成 | | app.(css | scss | wxss | ...) | 全局样式入口，支持 CSS、WXSS 与常见预处理器 | | pages/ | 主包页面目录 | | components/ | 主包组件目录，默认参与自动导入扫描 | | <subPackageRoot>/pages/ | 已声明分包 root 下的页面目录 | | custom-tab-bar/ | tabBar.custom === true 时的固定入口 | | app-bar/ | appBar 开启时的固定入口 | | typed-router.d.ts / typed-components.d.ts / components.d.ts | 自动生成的类型声明文件 |

相关文档

• 自动路由
• 自动导入组件
• 分包指南
• 手动集成