配置选项

create-vite-taro 生成的项目在 vite.config.ts 中调用 vpt()。以下是 vpt() 的全部公开选项。

`target`

选择本次构建的目标：

target: 'wx'

值	输出
`wx`	微信小程序
`zfb`	支付宝小程序
`tt`	抖音小程序
`h5`	Web 应用

`renderer`

小程序渲染器，默认 template。

renderer: 'dom'

值	行为
`template`	使用 Taro 的递归模板与 `setData()` 进行渲染。
`dom`	使用原生 DOM 渲染，不需要 `wxml`，零 `setData()` 调用，性能极佳，与原生持平；当前支持微信、抖音。支付宝暂不支持。

微信 DOM 模式需要开启 glass-easel。 DOM 渲染同时支持 Webview 和 Skyeline。

DOM 模式为了保证兼容性，仍然会打包递归模版文件，在运行时检测到当前环境不支持 DOM 渲染时，无缝退回到 template 模式。

首页性能图表展示微信开发者工具中的实测对比；benchmark-demo包含可复现的 benchmark。

`app`

指定 App 组件：

app: 'src/app.tsx'

路径相对于 Vite 项目根目录。该文件必须默认导出 React 组件：

import type { PropsWithChildren } from 'react'
import { useLaunch } from 'virtual:taro/api'
import { View } from 'virtual:taro/components'
import './app.css'

function App({ children }: PropsWithChildren) {
    useLaunch(() => {
        console.log('App launched')
    })

    return <View className="app-shell">{children}</View>
}

export default App

页面内容通过 children 传入。App 返回的 JSX 会在 Web 和小程序目标中包裹页面，因此全局布局、全局样式、 App 生命周期、React Provider 和应用级初始化都可以放在这里。

小程序构建仍然只有一个 React App 实例。页面切换不会为每个原生 Page 重新创建 App；App 的 Context、Hook 状态、Effect 和 Ref 都沿普通的 App → Page React 父子关系保留。每个原生 Page 仍使用独立的数据更新边界。完整用法和生命周期区别参见 App 与页面。

`pages`

声明应用的全部页面：

pages: [
    {
        path: 'pages/home/index',
        config: {
            navigationBarTitleText: '首页'
        }
    },
    {
        path: 'pages/profile/index',
        config: {
            navigationBarTitleText: '个人中心',
            enablePullDownRefresh: true
        }
    }
]

vpt 不扫描目录。新增页面时，必须创建页面文件并把它加入 pages。

`pages[].path`

path 同时是页面路由和 src 下的源码路径，不包含文件扩展名：

path: 'pages/profile/index'
源码: src/pages/profile/index.tsx

页面文件必须默认导出 React 组件。数组顺序决定小程序 app.json.pages 和 H5 路由顺序；第一项是小程序首页。

`pages[].config`

页面配置可选；省略时等同于 {}：

{
    path: 'pages/about/index'
}

小程序构建将它写入对应的页面 JSON，H5 构建将它用于对应路由。

usingComponents 由 vpt 自动管理，无需填写。接入方式参见原生组件。

微信目标请在每个页面的 config 中显式设置 glassEaselWebview: true，同时保留 appJson 顶层的 componentFramework: 'glass-easel' 和 glassEaselWebview: true。这既适用于 Skyline，也适用于普通 WebView 页面，与是否开启 prerender 无关。

`pages[].prerender`

可选布尔值，默认关闭。省略或设为 false 时，直接注册原始 Page 配置；设为 true 时，尝试同步渲染并序列化 App/Page 首屏数据。

以下为微信页面示例，App 配置沿用上面的 glass-easel 设置：

pages: [
    {
        path: 'pages/gallery/index',
        config: { glassEaselWebview: true }
    },
    {
        path: 'pages/detail/index',
        prerender: true,
        config: { glassEaselWebview: true }
    }
]

适合需要在原生 onLoad 前提供目标节点的场景，例如 Skyline 共享元素转场。

预渲染复用现有 React App 根和 Page 实例，不提前派发生命周期；但 React 渲染和 Effect 可能早于原生 onLoad，不要依赖此时已有原生页面上下文。

`appJson`

配置应用级行为：

appJson: {
    lazyCodeLoading: 'requiredComponents',
    window: {
        navigationBarTitleText: '示例应用'
    },
    tabBar: {
        color: '#64748b',
        selectedColor: '#16a34a',
        list: [
            { pagePath: 'pages/home/index', text: '首页' },
            { pagePath: 'pages/profile/index', text: '我的' }
        ]
    }
}

小程序构建用它生成 app.json。H5 构建也会使用其中适用于 Taro Web 的应用配置。

以下由 vpt 自动维护，无需填写：

字段	来源
`pages`	根据 `pages` 选项生成
`subPackages` / `subpackages`	根据自动分包结果生成
`routes`	根据 `pages` 生成 H5 路由

即使传入这些字段，vpt 也会用构建结果替换它们。

appJson 接受普通 JSON 对象，按当前目标的原生配置原样输出，不在微信、支付宝和抖音之间翻译字段。字段名称和取值以对应平台文档为准。

支付宝自定义 Tabs

支付宝设置 appJson.tabBar.customize: true 时，vpt 会在输出目录的 customize-tab-bar/ 中自动生成隐藏的原生占位组件。可直接在页面中使用 React 开发 Tabs 组件，通过 Taro.switchTab() 切换 Tab 页面。

应用通过 Vite 的 public 目录或其他插件提供的同名文件会保留，vpt 只补齐其余占位文件。

`projectConfigJson`

使用当前目标的原生字段配置开发者工具项目。以下为微信示例：

projectConfigJson: {
    appid: wechatAppId,
    projectname: 'vite-taro-app',
    compileType: 'miniprogram',
    setting: {
        compileHotReLoad: true,
        es6: false,
        enhance: false,
        urlCheck: false,
        skylineRenderEnable: false
    }
}

微信写入 project.config.json，支付宝写入 mini.project.json，抖音写入 project.config.json。

小程序监听构建（build:... --watch）会自动关闭生成配置中的开发者工具热重载：

目标	监听构建中强制设为 `false` 的字段
微信	`setting.compileHotReLoad`
支付宝	`developOptions.hotReload`
抖音	顶层 `compileHotReload` 和 `setting.compileHotReLoad`

`projectPrivateConfigJson`

可选。提供时写入对应平台的私有配置文件，不与 projectConfigJson 合并。微信和抖音监听构建会强制设置私有配置中的 setting.compileHotReLoad: false，避免覆盖共享配置的关闭设置；其余字段及支付宝私有配置原样输出：

projectPrivateConfigJson: {
    setting: {
        urlCheck: false
    }
}

微信写入 project.private.config.json；支付宝写入 .mini-ide/project-ide.json；抖音写入 project.private.config.json；H5 构建忽略该选项。

`sitemapJson`

可选。微信构建仅在提供该选项时生成 sitemap.json；支付宝、抖音和 H5 忽略它：

sitemapJson: {
    rules: [{ action: 'allow', page: '*' }]
}

`react`

可选。将配置原样传给 VPT 内置的 @vitejs/plugin-react。

React Compiler

在应用目录安装编译器。版本范围请以项目实际安装的 @vitejs/plugin-react 的 peerDependencies.oxc-transform-react 为准。可参考上游依赖声明，查看时请选择与安装版本对应的 tag。以下命令中的 ^0.152.0 仅为示例：

pnpm add -D 'oxc-transform-react@^0.152.0'

在现有 vpt({ ... }) 配置中启用：

react: {
    compiler: true
}

若希望只编译显式标记的组件，使用注解模式：

react: {
    compiler: {
        compilationMode: 'annotation'
    }
}

然后在组件函数开头添加 'use memo'：

import { View } from 'virtual:taro/components'

export function Greeting() {
    'use memo'

    return <View>Hello</View>
}

`polyfills`

可选。当小程序需要运行环境尚未提供的 JavaScript / Web API 时，用此选项补充：

polyfills: ['web.url', 'es.array.at', '...']

使用 core-js 模块名，不带 core-js/modules/ 前缀或 .js 后缀。无需额外安装 core-js，也无需在应用代码中手动导入。

缺失或不符合标准的全局 API 和原型方法会被补充或修复，符合标准的原生实现会保留。
省略或传入 [] 时，不添加任何可选 polyfill。
只打包所选模块及其依赖。polyfill 会增加小程序包体积，请按应用实际需求选择。
H5 忽略该选项；H5 的旧浏览器支持可另行配置 @vitejs/plugin-legacy。

需要 URL 和 URLSearchParams 时，选择 web.url 即可。如果还需要 URL.parse，使用 polyfills: ['web.url', 'web.url.parse']。

全局 API 安装在 globalThis 上。所有小程序目标都支持直接使用 new URL(...)、new URLSearchParams(...)，也可以通过 globalThis.URL、globalThis.URLSearchParams 访问，无需额外配置。

`hmr`

可选。为 vite serve 的小程序开发者工具选择源码更新方式：

hmr: {
    mode: 'interpreter'
}

`mode`	行为
`devtools`	默认值。把原生补丁写入项目，由小程序开发工具重新执行 Page。
`interpreter`	通过 Vite 现有 WebSocket 推送源码，使用解释器执行代码，不重新注册 Page。
`rebuild`	每次有效源码变化都重新生成完整原生项目并重启 App，不创建或应用增量补丁。

该选项不改变 H5 或生产构建输出。

生成的小程序配置文件

vpt 配置	WX 输出	ZFB 输出	TT 输出
`appJson` 和 `pages`	`app.json`	`app.json`	`app.json`
`pages[].config`	`${path}.json`	`${path}.json`	`${path}.json`
`projectConfigJson`	`project.config.json`	`mini.project.json`	`project.config.json`
`projectPrivateConfigJson`	`project.private.config.json`	`.mini-ide/project-ide.json`	`project.private.config.json`
`sitemapJson`（可选）	提供时生成 `sitemap.json`	—	—

Vite 配置

下面这些设置继续使用 Vite，不放入 vpt()：

需求	配置位置
输出目录	`build.outDir`
H5 部署基础路径	`base`
源码别名	`resolve.alias`
全局标识符替换	`define`
PostCSS	`css.postcss` 或 PostCSS 配置文件
静态文件	`public` 目录
开发服务器	`server`
其他构建扩展	Vite 插件

H5 需要项目根目录下的 index.html，其中包含挂载节点：

<div id="app"></div>

不需要 src/main.tsx，也不需要在 HTML 中添加入口脚本。vpt 会生成并注入入口。小程序构建都不使用 index.html。

小程序中的 `globalThis`

微信（wx）、支付宝（zfb）和抖音（tt）均支持直接使用 globalThis。vpt 自动提供统一的全局对象绑定，无需手动导入、配置 define 或添加 globalThis polyfill。

安装在全局对象上的 API 也可通过裸标识符访问，同名局部变量遵循正常的 JavaScript 作用域规则。

小程序中的浏览器式全局变量

小程序共用 Taro 浏览器兼容绑定，可以直接使用以下名称，无需额外安装依赖或手动导入：

document、navigator；
requestAnimationFrame、cancelAnimationFrame；
Element、SVGElement、MutationObserver；
history、location。

这些 API 是 Taro 提供的小程序兼容实现，并不提供完整的浏览器环境。需要 URL 和 URLSearchParams 时，如果运行环境未提供，请配置 polyfills: ['web.url']。

不读取 Taro 配置

vpt 不读取：

config/index.ts、config/dev.ts、config/prod.ts；
src/app.config.ts；
页面旁的 *.config.ts；
手写的 app.json 或页面 JSON；
手写的小程序分包声明。

已有 Taro 项目需要把这些配置移入 vite.config.ts。参见从 Taro 迁移。

使用独立 JSON 文件

如果希望把配置保留为真实 JSON 文件，可以在 vite.config.ts 中使用 Node.js fs 读取，再传给 vpt：

config/
├── app.json
├── pages/home.json
├── project.config.json
└── project.private.config.json

import { readFileSync } from 'node:fs'
import { defineConfig } from 'vite'
import vpt from 'vite-plugin-taro'

export default defineConfig({
    build: {
        outDir: 'dist/wx'
    },
    plugins: [
        vpt({
            target: 'wx',
            app: 'src/app.tsx',
            pages: [
                {
                    path: 'pages/home/index',
                    config: readJson('./config/pages/home.json')
                }
            ],
            appJson: readJson('./config/app.json'),
            projectConfigJson: readJson('./config/project.config.json'),
            projectPrivateConfigJson: readJson('./config/project.private.config.json')
        })
    ]
})

function readJson(relativePath: string): Record<string, unknown> {
    return JSON.parse(readFileSync(new URL(relativePath, import.meta.url), 'utf8'))
}

这些文件只是配置的存储方式，生成规则不变。例如，config/app.json 中的 pages 和分包声明仍会由 vpt 的构建结果替换。

配置选项

target

renderer

app

pages

pages[].path

pages[].config

pages[].prerender

appJson