vite-plugin-taro 0.1.6 → 0.1.8

package/README.en.md

@@ -4,13 +4,13 @@
 ![Vite compatibility](https://registry.vite.dev/api/badges?package=vite-plugin-taro&tool=vite)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-[简体中文](README.md) | English
+[简体中文](README.zh.md) | English
 
 Build WeChat Mini Apps with the latest standards-based frontend stack: Vite 8, React 19, and Tailwind CSS v4.
 
 `vite-plugin-taro` is for applications that want Taro's cross-platform React components and APIs, but prefer Vite instead of Taro webpack. You only need this plugin to build a complete WeChat Mini Program.
 
-Live demo: <https://sep2.github.io/vite-plugin-taro>. See [Sample app](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.en.md) how to run it locally.
+Live demo: <https://sep2.github.io/vite-plugin-taro>. See [Sample app](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.md) how to run it locally.
 
 - **Native Vite builds** Use standard Vite 8 config instead of legacy webpack configuration, with support for all Vite plugins.
 - **Hot reload** Both WeChat Mini Program and H5 support dev-mode watch, with Vite 8 HMR/rebuilds for fast feedback.
@@ -496,7 +496,8 @@ Common scripts:
 | `pnpm build:sample:h5` | Build the H5 sample app to `packages/loan-genius/dist/h5`. |
 | `pnpm preview:sample:h5` | Preview the built H5 sample. |
 | `pnpm publish:dry` | Dry-run package validation and publishing. |
-| `pnpm publish:all` | Publish the public packages in dependency order. |
+| `pnpm release <version\|bump>` | Validate, bump versions, create the release commit and tag, and push to trigger CI publishing. |
+| `pnpm publish:all` | Publish the public packages in dependency order; mainly used by the tag-based Trusted Publishing workflow. |
 
 ## Limitations
 
@@ -518,18 +519,25 @@ Common scripts:
 
 ## Release workflow
 
-Validate the publishable packages before publishing:
+This repository publishes automatically with npm Trusted Publishing and GitHub Actions. Normal pushes to `main` do not publish; only tags matching `v*.*.*` trigger `.github/workflows/publish.yml`.
+
+Create a release:
 
 ```sh
-pnpm publish:dry
+pnpm release patch
 ```
 
-Publish all public packages in the required order:
+`pnpm release` requires a clean `main` working tree, runs `pnpm version:bump`, validates with `pnpm publish:dry -- --no-git-check`, creates the `chore: release vX.Y.Z` commit and `vX.Y.Z` tag, then pushes the branch and tag to trigger CI. You can also release an exact version or prerelease:
 
 ```sh
-pnpm publish:all
+pnpm release 0.2.0
+pnpm release prerelease --preid beta
+pnpm release patch --dry-run
+pnpm release patch --no-push
 ```
 
+CI runs `pnpm publish:all -- --no-git-check`, packs packages in dependency order, and publishes public packages through npm OIDC. Do not configure `NPM_TOKEN` for the publish workflow; each npm package's Trusted Publisher should point to `publish.yml`.
+
 ## License
 
 MIT

package/README.md

@@ -4,114 +4,114 @@
 ![Vite compatibility](https://registry.vite.dev/api/badges?package=vite-plugin-taro&tool=vite)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-简体中文 | [English](README.en.md)
+[简体中文](README.zh.md) | English
 
-使用最新标准化前端技术栈 Vite 8、React 19 和 Tailwind CSS v4 构建微信小程序。
+Build WeChat Mini Apps with the latest standards-based frontend stack: Vite 8, React 19, and Tailwind CSS v4.
 
-`vite-plugin-taro` 适用于希望使用 Taro 跨平台 React 组件和 API，但更偏好 Vite 而非 Taro webpack 的应用。你只需要这个插件，就能构建完整的微信小程序。
+`vite-plugin-taro` is for applications that want Taro's cross-platform React components and APIs, but prefer Vite instead of Taro webpack. You only need this plugin to build a complete WeChat Mini Program.
 
-在线演示：<https://sep2.github.io/vite-plugin-taro>。如何在本地运行，请参见[示例应用](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.md)。
+Live demo: <https://sep2.github.io/vite-plugin-taro>. See [Sample app](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.md) how to run it locally.
 
-- **原生 Vite 构建** 使用标准 Vite 8 配置，无需维护老旧的 webpack 配置，并支持所有 Vite 插件。
-- **热更新** 微信小程序与 H5 都支持开发模式 watch，基于 Vite 8 热更新/快速重建即时预览。
-- **依托成熟 Taro 能力** 复用久经实战检验的 Taro API 和组件，完整使用 Taro 跨端能力。
-- **Tailwind 就绪** 内置 Tailwind CSS v4 支持，微信小程序与 H5 样式开箱即用。
-- **条件编译** 支持 Taro 风格 `#ifdef` / `#ifndef` / `#if`，可按微信 / Web 裁剪代码和样式。
-- **工作区友好** 支持普通项目与 monorepo，兼容 npm、pnpm、Yarn、Bun 等包管理器。
-- **类型友好** 项目全链路支持 TypeScript。
-- **微信 Skyline** 支持微信小程序 Skyline 渲染模式输出。
+- **Native Vite builds** Use standard Vite 8 config instead of legacy webpack configuration, with support for all Vite plugins.
+- **Hot reload** Both WeChat Mini Program and H5 support dev-mode watch, with Vite 8 HMR/rebuilds for fast feedback.
+- **Battle-tested Taro foundation** Use the full set of Taro APIs and components instead of reinventing cross-platform primitives.
+- **Tailwind ready** Built-in Tailwind CSS v4 support for both WeChat Mini Program and H5 styles.
+- **Conditional compilation** Use Taro-style `#ifdef` / `#ifndef` / `#if` blocks to split code and styles by WeChat / web target.
+- **Workspace friendly** Supports standalone apps and monorepos, with npm, pnpm, Yarn, Bun, and other package managers.
+- **Type-friendly** The project supports TypeScript all the way.
+- **WeChat Skyline** Support WeChat Mini Program output with Skyline rendering mode.
 
-## 快速开始
+## Quick start
 
-新应用推荐使用 `create-vite-taro`。它会生成 Vite 8 + React 19 + Tailwind CSS v4 + Taro 4 项目。
+Use `create-vite-taro` for new apps. It scaffolds a Vite 8 + React 19 + Tailwind CSS v4 + Taro 4 project.
 
-### 1. 创建并安装
+### 1. Create and install
 
 ```sh
-# 使用默认模板创建新应用
+# Create a new app from the default template
 npm create vite-taro@latest my-app
 
-# 进入项目并安装依赖
+# Enter the project and install dependencies
 cd my-app
 npm install
 ```
 
-### 2. 配置微信小程序 App Id
+### 2. Configure WeChat Mini Program App ID
 
-模板会创建 `.env.local`。请将 `VITE_PLUGIN_TARO_WECHAT_APP_ID` 设置为你的微信小程序 App Id。
+The template creates `.env.local`. Set `VITE_PLUGIN_TARO_WECHAT_APP_ID` to your WeChat Mini Program App ID.
 
-### 3. 开发模式运行
+### 3. Run in development
 
 ```sh
-# 微信小程序：以 watch 模式重新构建 dist/wx
+# WeChat Mini Program: rebuild dist/wx in watch mode
 npm run dev:wx
 
-# 然后在微信开发者工具中打开 dist/wx
+# Then open dist/wx in WeChat DevTools
 
-# H5：启动 Vite 开发服务器
+# H5: start the Vite dev server
 npm run dev:h5
 
-# 然后在浏览器中打开标准 Vite 地址
+# Then open the standard Vite dev URL in your browser
 # http://localhost:5173
 ```
 
-你可以在两个终端中同时运行 `npm run dev:wx` 和 `npm run dev:h5`。
+You can keep `npm run dev:wx` and `npm run dev:h5` running at the same time in separate terminals.
 
-提示：受微信限制，开发者工具热重载有时不会完整生效。建议日常优先使用 H5 的 Vite 热更新快速调试，并定期在微信开发者工具中验证小程序端效果。
+Note: Because of WeChat DevTools and Mini Program runtime limitations, hot reload/fast rebuilds for the WeChat target may not always apply cleanly. For day-to-day iteration, prefer the H5 Vite dev server for fast feedback, and periodically verify the Mini Program result in WeChat DevTools.
 
-### 4. 构建、预览和类型检查
+### 4. Build, preview, and typecheck
 
 ```sh
-# 生产微信小程序产物
+# Production WeChat Mini Program output
 npm run build:wx
 
-# 生产 H5 产物
+# Production H5 output
 npm run build:h5
 
-# 预览构建后的 H5 应用
+# Preview the built H5 app
 npm run preview:h5
 
-# 使用 tsgo 进行类型检查
+# Typecheck with tsgo
 npm run typecheck
 ```
 
-### 5. 使用 Taro 虚拟模块
+### 5. Use Taro virtual modules
 
-应用代码请使用这些导入：
+Use these imports in app code:
 
 ```tsx
 import Taro from 'virtual:taro/api'
 import { Text, View } from 'virtual:taro/components'
 ```
 
-| 导入 | 用途 |
+| Import | Use |
 | --- | --- |
-| `virtual:taro/components` | Taro React 组件，例如 `View`、`Text`、`Button`、`Image` 和 `ScrollView`。 |
-| `virtual:taro/api` | Taro API 和 hooks，例如 `Taro.navigateTo`、`Taro.getWindowInfo` 和 `Taro.useLaunch`。 |
+| `virtual:taro/components` | Taro React components such as `View`, `Text`, `Button`, `Image`, and `ScrollView`. |
+| `virtual:taro/api` | Taro APIs and hooks such as `Taro.navigateTo`, `Taro.getWindowInfo`, and `Taro.useLaunch`. |
 
-用法与 Taro 本身一致；组件和 API 的具体用法请参考 [Taro 官网](https://docs.taro.zone)。
+Usage is the same as Taro itself; see the [Taro website](https://docs.taro.zone) for component and API details.
 
-你不再需要安装 `@tarojs/*` 包；应用代码也不要从 `@tarojs/*` 导入。
+You no longer need to install `@tarojs/*` packages; application code should not import from `@tarojs/*`.
 
 
-## 手动接入已有应用
+## Manual setup for existing apps
 
-已有应用或自定义项目结构，可以按下面的步骤手动接入插件。先安装插件：
+For existing apps or custom project layouts, follow the steps below to wire the plugin manually. First, install the plugin:
 
 ```sh
 npm install -D vite-plugin-taro
 ```
 
-你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 检查器，以及 Node/React 类型包。如果应用尚未安装它们，请安装缺失的包：
+Your app must also provide Vite 8, React 19, React DOM 19, a TypeScript checker, and Node/React type packages. If your app does not already have them, install the missing packages:
 
 ```sh
 npm install react react-dom
 npm install -D vite @typescript/native-preview @types/node @types/react @types/react-dom
 ```
 
-你不应再直接依赖任何 `@tarojs/*` 包。如果已经依赖，请将它们移除。
+You should NOT have direct dependencies on `@tarojs/*` packages anymore. Remove them if you have.
 
-下面的步骤会创建如下源码结构：
+The steps below create this source shape:
 
 ```text
 my-app/
@@ -127,11 +127,11 @@ my-app/
             └── index.tsx
 ```
 
-你也可以参考 [packages/loan-genius](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius) 中的示例布局。
+You can also see a sample layout at [packages/loan-genius](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius).
 
-### 1. 添加 TypeScript 声明
+### 1. Add TypeScript declarations
 
-将插件客户端类型添加到 `tsconfig.json`，让 TypeScript 识别虚拟模块：
+Add the plugin client types to `tsconfig.json` so TypeScript knows about the virtual modules:
 
 ```json
 {
@@ -144,9 +144,9 @@ my-app/
 }
 ```
 
-### 2. 配置 Vite
+### 2. Configure Vite
 
-创建 `vite.config.ts`，并从环境变量中选择插件目标：
+Create `vite.config.ts` and choose the plugin target from an environment variable:
 
 ```ts
 import { defineConfig, loadEnv } from 'vite'
@@ -200,17 +200,17 @@ export default defineConfig(({ mode }) => {
 })
 ```
 
-重要约定：
+Important conventions:
 
-- 每次 Vite 运行时，`target` 必须是 `wx` 或 `h5`。
-- `app` 是 React 根应用组件模块，应默认导出应用组件。
-- 每个 `pages[].path` 都会映射到 `src/${path}.tsx` 文件。例如，`pages/index/index` 需要 `src/pages/index/index.tsx`。
-- `appJson.pages` 会根据 `pages` 自动生成；你在 `appJson` 中传入的任何 `pages` 字段都会被覆盖。
-- 插件不会读取 Taro CLI 配置文件，例如 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 文件。请通过插件选项传入应用和页面配置。
+- `target` must be `wx` or `h5` for each Vite run.
+- `app` is the root React app component module. It should default-export the app component.
+- Every `pages[].path` maps to a file at `src/${path}.tsx`. For example, `pages/index/index` requires `src/pages/index/index.tsx`.
+- `appJson.pages` is generated from `pages`; any `pages` field you put in `appJson` is overwritten.
+- The plugin does not read Taro CLI config files such as `config/index.ts`, `app.config.ts`, or page `config.ts` files. Pass app and page config through the plugin options.
 
-### 3. 创建应用组件
+### 3. Create the app component
 
-`src/app.ts` 是共享应用包装组件。它会通过 `children` 接收当前页面。
+`src/app.ts` is the shared application wrapper. It receives the current page as `children`.
 
 ```tsx
 import Taro from 'virtual:taro/api'
@@ -228,11 +228,11 @@ function App({ children }: PropsWithChildren) {
 export default App
 ```
 
-请在应用组件中导入全局样式。微信构建会将它们收集到 `app.wxss`，H5 输出也会包含它们。
+Import global styles from the app component. They are collected into `app.wxss` for WeChat builds and included in H5 output.
 
-### 4. 创建页面组件
+### 4. Create a page component
 
-`src/pages/index/index.tsx` 是 `pages/index/index` 对应的 React 页面组件。
+`src/pages/index/index.tsx` is the React component for `pages/index/index`.
 
 ```tsx
 import Taro from 'virtual:taro/api'
@@ -256,9 +256,9 @@ export default function IndexPage() {
 }
 ```
 
-### 5. 添加 H5 HTML 外壳
+### 5. Add the H5 HTML shell
 
-对于 H5，请保留一个普通的 Vite `index.html`，并包含 `#app` 挂载节点。插件会自动注入生成的 Taro H5 入口，因此你不需要普通 Vite 的 `src/main.tsx` 脚本。
+For H5, keep a normal Vite `index.html` with an `#app` mount node. The plugin injects the generated Taro H5 entry automatically, so you do not need a normal Vite `src/main.tsx` script.
 
 ```html
 <!doctype html>
@@ -274,9 +274,9 @@ export default function IndexPage() {
 </html>
 ```
 
-### 6. 添加脚本
+### 6. Add scripts
 
-使用与 `create-vite-taro` 生成项目一致的脚本：
+Use the same scripts generated by `create-vite-taro`:
 
 ```json
 {
@@ -291,27 +291,27 @@ export default function IndexPage() {
 }
 ```
 
-在 Windows shell 中，请使用 `cross-env`。
+On Windows shells, use `cross-env`.
 
-### 7. 运行每个目标
+### 7. Run each target
 
 ```sh
-npm run dev:wx       # 以 watch 模式重新构建 dist/wx
-npm run dev:h5       # 启动 H5 开发服务器
-npm run build:wx     # 构建 dist/wx
-npm run build:h5     # 构建 dist/h5
-npm run preview:h5   # 预览 dist/h5
-npm run typecheck    # 使用 tsgo 进行类型检查
+npm run dev:wx       # Rebuild dist/wx in watch mode
+npm run dev:h5       # Start the H5 dev server
+npm run build:wx     # Build dist/wx
+npm run build:h5     # Build dist/h5
+npm run preview:h5   # Preview dist/h5
+npm run typecheck    # Typecheck with tsgo
 ```
 
-在微信开发者工具中打开生成的 `dist/wx` 目录。
+Open the generated `dist/wx` directory in WeChat DevTools.
 
-| 目标 | 含义 | 输出目录 |
+| Target | Meaning | Output dir |
 | --- | --- | --- |
-| `wx` | 开发/生产模式下的微信小程序。 | `dist/wx` |
-| `h5` | H5 生产输出。 | `dist/h5` |
+| `wx` | WeChat Mini Program in both dev/prod mode. | `dist/wx` |
+| `h5` | H5 production output. | `dist/h5` |
 
-## 选项
+## Options
 
 ```ts
 type VitePluginTaroTarget = 'wx' | 'h5'
@@ -331,22 +331,22 @@ type VitePluginTaroOptions = {
 }
 ```
 
-| 选项 | 描述 |
+| Option | Description |
 | --- | --- |
-| `target` | 本次 Vite 调用的活动目标。微信小程序使用 `wx`，Web 使用 `h5`。 |
-| `app` | 默认导出根 React 应用组件的源码文件，例如 `src/app.ts` 或 `src/app.tsx`。 |
-| `pages` | 有序页面列表。该顺序会成为 `app.json.pages` 和 H5 路由顺序。 |
-| `pages[].path` | 不带扩展名的 Taro 风格路由和输出路径，例如 `pages/index/index`。页面组件必须存在于 `src/${path}.tsx`。 |
-| `pages[].config` | 合并到生成的微信页面 JSON 和 H5 路由配置中的页面配置。 |
-| `appJson` | 基础应用配置。插件会用 `options.pages` 覆盖其中的 `pages` 字段。 |
-| `projectConfigJson` | `wx` 构建时输出的微信 `project.config.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
-| `sitemapJson` | `wx` 构建时输出的微信 `sitemap.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
+| `target` | Active target for this Vite invocation. Use `wx` for WeChat Mini Program and `h5` for Web. |
+| `app` | Source file that default-exports the root React app component, for example `src/app.ts` or `src/app.tsx`. |
+| `pages` | Ordered page list. The order becomes `app.json.pages` and the H5 route order. |
+| `pages[].path` | Taro-style route and output path without extension, for example `pages/index/index`. The page component must exist at `src/${path}.tsx`. |
+| `pages[].config` | Page config merged into the generated WeChat page JSON and H5 route config. |
+| `appJson` | Base app config. The plugin overwrites the `pages` field from `options.pages`. |
+| `projectConfigJson` | WeChat `project.config.json` content emitted for `wx` builds. It is required by the option type even when the current target is `h5`. |
+| `sitemapJson` | WeChat `sitemap.json` content emitted for `wx` builds. It is required by the option type even when the current target is `h5`. |
 
-## 样式
+## Styling
 
-你可以使用普通 CSS、CSS Modules 或 Tailwind CSS v4。
+You can use plain CSS, CSS modules, or Tailwind CSS v4.
 
-对于 Tailwind CSS v4，请从全局 CSS 文件（例如 `src/app.css`）导入 Tailwind：
+For Tailwind CSS v4, import Tailwind from a global CSS file such as `src/app.css`:
 
 ```css
 @import "tailwindcss/theme.css";
@@ -356,11 +356,11 @@ type VitePluginTaroOptions = {
 @source "./";
 ```
 
-插件会为 `wx` 构建注册 `weapp-tailwindcss`，并为 `h5` 构建注册 `@tailwindcss/vite`。对于 `wx`，Vite 输出的 CSS 会被收集到 `app.wxss`，并为每个页面生成配套的 `.wxss` 文件。
+The plugin registers `weapp-tailwindcss` for `wx` builds and `@tailwindcss/vite` for `h5` builds. For `wx`, CSS emitted by Vite is collected into `app.wxss`, and page `.wxss` companion files are emitted for each page.
 
-## 条件编译
+## Conditional compilation
 
-插件会在 Vite 解析源码前移除未激活的 Taro 风格条件注释块。它适用于 `node_modules` 之外的 TypeScript、JavaScript、JSX/TSX、CSS、Sass、Less 和 Stylus 文件。
+The plugin strips inactive Taro-style conditional comment blocks before Vite parses source. This works in TypeScript, JavaScript, JSX/TSX, CSS, Sass, Less, and Stylus files outside `node_modules`.
 
 ```ts
 // #ifdef wx
@@ -380,15 +380,15 @@ console.log('fallback')
 // #endif
 ```
 
-支持的指令包括 `#ifdef`、`#ifndef`、`#if`、`#elif`、`#else` 和 `#endif`。条件使用插件目标标记 `wx` 和 `h5`；`#if` 表达式支持 `!`、`&&` 和 `||`。
+Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Conditions use the plugin target tokens `wx` and `h5`; `#if` expressions support `!`, `&&`, and `||`.
 
-## 按目标输出
+## Output by target
 
-### 微信小程序
+### WeChat Mini Program
 
-对于 `target: 'wx'`，插件会配置 Vite，输出微信兼容的 CommonJS chunk 和小程序配套文件。
+For `target: 'wx'`, the plugin configures Vite to emit WeChat-compatible CommonJS chunks and Mini Program companion files.
 
-典型输出：
+Typical output:
 
 ```text
 dist/wx/
@@ -405,74 +405,74 @@ dist/wx/
 └── pages/**
 ```
 
-请使用微信开发者工具打开 `dist/wx`；不要打开源码项目目录。
+Open `dist/wx` with WeChat DevTools; do not open the source project directory.
 
 ### H5
 
-对于 `target: 'h5'`，插件会向 `index.html` 注入生成模块，导入 Taro 的 H5 组件样式，根据 `pages` 构建路由记录，并使用 Taro 的 hash-history 路由挂载应用。路由使用配置中的页面路径，例如 `#/pages/index/index`。
+For `target: 'h5'`, the plugin injects a generated module into `index.html`, imports Taro's H5 component styles, builds route records from `pages`, and mounts the app with Taro's hash-history router. Routes use the page paths from your config, for example `#/pages/index/index`.
 
-## 从 Taro 迁移
+## Migrating from Taro
 
-你可以保留大多数 React 页面组件、业务逻辑、资源和样式，但构建入口会从 Taro CLI 配置迁移到 Vite 配置。
+You can keep most React page components, business logic, assets, and styles, but the build entry moves from Taro CLI config to Vite config.
 
-迁移清单：
+Migration checklist:
 
-1. 安装 `vite-plugin-taro`，并创建包含 `vitePluginTaro(...)` 的 `vite.config.ts`。
-2. 将应用配置和页面配置移到 `vite.config.ts` 中。插件不会读取 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 等 Taro 文件。
-3. 在 `pages` 中注册每个页面。每个页面路径都必须匹配 `src/${path}.tsx`。
-4. 将 Taro 脚本替换为设置 `VITE_PLUGIN_TARO_TARGET=wx` 或 `VITE_PLUGIN_TARO_TARGET=h5` 的 Vite 脚本。
-5. 对于 H5，添加普通 Vite `index.html`，其中包含 `<div id="app"></div>`，且不要添加单独的 `src/main.tsx` 入口。
-6. 将应用代码中的 `@tarojs/*` 导入替换为插件虚拟模块。
+1. Install `vite-plugin-taro` and create `vite.config.ts` with `vitePluginTaro(...)`.
+2. Move app config and page config into the plugin options. The plugin does not read Taro CLI files such as `config/index.ts`, `app.config.ts`, or page `config.ts` files.
+3. Register every page in `pages`. Each page path must match `src/${path}.tsx`.
+4. Replace Taro scripts with Vite scripts that set `VITE_PLUGIN_TARO_TARGET=wx` or `VITE_PLUGIN_TARO_TARGET=h5`.
+5. For H5, add a normal Vite `index.html` with `<div id="app"></div>` and no separate `src/main.tsx` entry.
+6. Replace application imports from `@tarojs/*` with the plugin virtual modules.
 
-迁移前：
+Before:
 
 ```tsx
 import Taro from '@tarojs/taro'
 import { Text, View } from '@tarojs/components'
 ```
 
-迁移后：
+After:
 
 ```tsx
 import Taro from 'virtual:taro/api'
 import { Text, View } from 'virtual:taro/components'
 ```
 
-应用代码中禁止直接导入 `@tarojs/*`。请让插件负责 Taro 运行时解析，使微信和 H5 构建都获得正确的目标特定别名。
+Direct `@tarojs/*` imports in application code are forbidden. Let the plugin own Taro runtime resolution so WeChat and H5 builds receive the correct target-specific aliases.
 
-## 示例应用
+## Sample app
 
-示例应用位于 [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius)。它展示了页面约定、目标选择、微信输出、H5 路由和 Tailwind 样式。
+The sample app lives in [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius). It demonstrates the page convention, target selection, WeChat output, H5 routing, and Tailwind styling.
 
 ```sh
 git clone https://github.com/sep2/vite-plugin-taro.git
 
-# 安装依赖
+# Install dependencies
 pnpm install
 
-# 首次运行，生成打过补丁的 Taro 包
+# Run once, it generates the patched Taro packages
 pnpm prepare:taro
 
-# 构建插件，供示例应用使用
+# Build the plugin for sample app to use
 pnpm build:plugin
 
-# 运行微信示例应用
+# Run the sample app in WeChat
 pnpm dev:sample:wx
 
-# 将示例应用构建为微信输出
+# Build the sample app to WeChat output
 pnpm build:sample:wx
 
-# 以开发模式运行 H5 示例应用
+# Run the sample app in H5 dev mode
 pnpm dev:sample:h5
 
-# 将示例应用构建为 H5 输出并预览
+# Build the sample app to H5 output and preview it
 pnpm build:sample:h5
 pnpm preview:sample:h5
 ```
 
-使用微信开发者工具打开 `packages/loan-genius/dist/wx`，以测试小程序输出。
+Open `packages/loan-genius/dist/wx` with WeChat DevTools to test the Mini Program output.
 
-## 开发本仓库
+## Develop this repository
 
 ```sh
 pnpm install
@@ -481,55 +481,63 @@ pnpm build:plugin
 pnpm typecheck
 ```
 
-常用脚本：
+Common scripts:
 
-| 脚本 | 描述 |
+| Script | Description |
 | --- | --- |
-| `pnpm prepare:taro` | 从上游 npm tarball 和本地 patch 文件重新生成打过补丁的 React 19 Taro 包。 |
-| `pnpm build:plugin` | 将 `packages/vite-plugin-taro` 构建到 `dist`。 |
-| `pnpm typecheck` | 使用 `tsgo` 对插件和示例应用进行类型检查。 |
-| `pnpm lint` | 运行 Biome 检查。 |
-| `pnpm format` | 应用 Biome 格式化。 |
-| `pnpm dev:sample:wx` | 以 watch 模式构建微信小程序示例。请先构建插件。 |
-| `pnpm dev:sample:h5` | 以 Vite 开发模式启动 H5 示例应用。请先构建插件。 |
-| `pnpm build:sample:wx` | 将微信小程序示例构建到 `packages/loan-genius/dist/wx`。 |
-| `pnpm build:sample:h5` | 将 H5 示例应用构建到 `packages/loan-genius/dist/h5`。 |
-| `pnpm preview:sample:h5` | 预览构建后的 H5 示例。 |
-| `pnpm publish:dry` | 干运行包校验和发布流程。 |
-| `pnpm publish:all` | 按依赖顺序发布公开包。 |
-
-## 限制
-
-- 目前只生成 `wx` 和 `h5` 目标。
-- 应用代码不能直接导入 `@tarojs/*` 包。
-
-## 排查问题
-
-| 问题 | 检查项 |
+| `pnpm prepare:taro` | Regenerate the patched React 19 Taro packages from upstream npm tarballs and local patch files. |
+| `pnpm build:plugin` | Build `packages/vite-plugin-taro` into `dist`. |
+| `pnpm typecheck` | Typecheck the plugin and sample app with `tsgo`. |
+| `pnpm lint` | Run Biome checks. |
+| `pnpm format` | Apply Biome formatting. |
+| `pnpm dev:sample:wx` | Build the sample WeChat Mini Program in watch mode. Build the plugin first. |
+| `pnpm dev:sample:h5` | Start the sample H5 app in Vite dev mode. Build the plugin first. |
+| `pnpm build:sample:wx` | Build the WeChat Mini Program sample to `packages/loan-genius/dist/wx`. |
+| `pnpm build:sample:h5` | Build the H5 sample app to `packages/loan-genius/dist/h5`. |
+| `pnpm preview:sample:h5` | Preview the built H5 sample. |
+| `pnpm publish:dry` | Dry-run package validation and publishing. |
+| `pnpm release <version\|bump>` | Validate, bump versions, create the release commit and tag, and push to trigger CI publishing. |
+| `pnpm publish:all` | Publish the public packages in dependency order; mainly used by the tag-based Trusted Publishing workflow. |
+
+## Limitations
+
+- Only `wx` and `h5` targets are generated today.
+- Application code must not import `@tarojs/*` packages directly.
+
+## Troubleshooting
+
+| Problem | Check |
 | --- | --- |
-| `VITE_PLUGIN_TARO_TARGET must be "wx" or "h5"` | 在脚本或 `.env` 文件中设置目标环境变量。 |
-| `pnpm install` 提示忽略了依赖构建脚本 | 运行 `pnpm approve-builds`，按提示批准需要构建的依赖。 |
-| 页面无法解析 | 确认 `pages[].path` 有匹配的 `src/${path}.tsx` 文件。 |
-| 微信开发者工具无法打开应用 | 打开生成的 `dist/wx` 文件夹，并检查 `projectConfigJson.appid`。 |
-| H5 显示空白页 | 确保 `index.html` 中保留 `<div id="app"></div>`，已注册插件，并避免添加单独的默认 Vite `main.tsx` 入口。 |
-| Taro API 缺失或行为不同 | 移除应用代码中直接导入的 `@tarojs/*`，并从 `virtual:taro/api` 导入 Taro。 |
-| 组件在 H5 上渲染时缺少预期样式 | 从 `virtual:taro/components` 导入组件，并确保 `h5` 目标启用了插件。 |
-| Tailwind 类没有生效 | 确保全局 CSS 导入 Tailwind，并包含覆盖源码文件的 `@source` 路径。 |
+| `VITE_PLUGIN_TARO_TARGET must be "wx" or "h5"` | Set the target environment variable in your script or `.env` file. |
+| `pnpm install` says dependency build scripts were ignored | Run `pnpm approve-builds` and approve the requested dependency build scripts. |
+| A page cannot be resolved | Confirm that `pages[].path` has a matching `src/${path}.tsx` file. |
+| WeChat DevTools cannot open the app | Open the generated `dist/wx` folder and check `projectConfigJson.appid`. |
+| H5 shows a blank page | Keep `<div id="app"></div>` in `index.html`, register the plugin, and avoid adding a separate default Vite `main.tsx` entry. |
+| Taro APIs are missing or behave differently | Remove direct `@tarojs/*` imports from application code and import Taro from `virtual:taro/api`. |
+| Components render without expected styles on H5 | Import components from `virtual:taro/components` and keep the plugin enabled for the `h5` target. |
+| Tailwind classes do not appear | Ensure your global CSS imports Tailwind and includes an `@source` path that covers your source files. |
 
-## 发布流程
+## Release workflow
 
-发布前先验证可发布包：
+This repository publishes automatically with npm Trusted Publishing and GitHub Actions. Normal pushes to `main` do not publish; only tags matching `v*.*.*` trigger `.github/workflows/publish.yml`.
+
+Create a release:
 
 ```sh
-pnpm publish:dry
+pnpm release patch
 ```
 
-按必要顺序发布所有公开包：
+`pnpm release` requires a clean `main` working tree, runs `pnpm version:bump`, validates with `pnpm publish:dry -- --no-git-check`, creates the `chore: release vX.Y.Z` commit and `vX.Y.Z` tag, then pushes the branch and tag to trigger CI. You can also release an exact version or prerelease:
 
 ```sh
-pnpm publish:all
+pnpm release 0.2.0
+pnpm release prerelease --preid beta
+pnpm release patch --dry-run
+pnpm release patch --no-push
 ```
 
-## 许可证
+CI runs `pnpm publish:all -- --no-git-check`, packs packages in dependency order, and publishes public packages through npm OIDC. Do not configure `NPM_TOKEN` for the publish workflow; each npm package's Trusted Publisher should point to `publish.yml`.
+
+## License
 
 MIT

package/README.zh.md

@@ -0,0 +1,543 @@
+# vite-plugin-taro
+
+[![npm version](https://img.shields.io/npm/v/vite-plugin-taro.svg)](https://www.npmjs.com/package/vite-plugin-taro)
+![Vite compatibility](https://registry.vite.dev/api/badges?package=vite-plugin-taro&tool=vite)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+简体中文 | [English](README.md)
+
+使用最新标准化前端技术栈 Vite 8、React 19 和 Tailwind CSS v4 构建微信小程序。
+
+`vite-plugin-taro` 适用于希望使用 Taro 跨平台 React 组件和 API，但更偏好 Vite 而非 Taro webpack 的应用。你只需要这个插件，就能构建完整的微信小程序。
+
+在线演示：<https://sep2.github.io/vite-plugin-taro>。如何在本地运行，请参见[示例应用](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.zh.md)。
+
+- **原生 Vite 构建** 使用标准 Vite 8 配置，无需维护老旧的 webpack 配置，并支持所有 Vite 插件。
+- **热更新** 微信小程序与 H5 都支持开发模式 watch，基于 Vite 8 热更新/快速重建即时预览。
+- **依托成熟 Taro 能力** 复用久经实战检验的 Taro API 和组件，完整使用 Taro 跨端能力。
+- **Tailwind 就绪** 内置 Tailwind CSS v4 支持，微信小程序与 H5 样式开箱即用。
+- **条件编译** 支持 Taro 风格 `#ifdef` / `#ifndef` / `#if`，可按微信 / Web 裁剪代码和样式。
+- **工作区友好** 支持普通项目与 monorepo，兼容 npm、pnpm、Yarn、Bun 等包管理器。
+- **类型友好** 项目全链路支持 TypeScript。
+- **微信 Skyline** 支持微信小程序 Skyline 渲染模式输出。
+
+## 快速开始
+
+新应用推荐使用 `create-vite-taro`。它会生成 Vite 8 + React 19 + Tailwind CSS v4 + Taro 4 项目。
+
+### 1. 创建并安装
+
+```sh
+# 使用默认模板创建新应用
+npm create vite-taro@latest my-app
+
+# 进入项目并安装依赖
+cd my-app
+npm install
+```
+
+### 2. 配置微信小程序 App Id
+
+模板会创建 `.env.local`。请将 `VITE_PLUGIN_TARO_WECHAT_APP_ID` 设置为你的微信小程序 App Id。
+
+### 3. 开发模式运行
+
+```sh
+# 微信小程序：以 watch 模式重新构建 dist/wx
+npm run dev:wx
+
+# 然后在微信开发者工具中打开 dist/wx
+
+# H5：启动 Vite 开发服务器
+npm run dev:h5
+
+# 然后在浏览器中打开标准 Vite 地址
+# http://localhost:5173
+```
+
+你可以在两个终端中同时运行 `npm run dev:wx` 和 `npm run dev:h5`。
+
+提示：受微信限制，开发者工具热重载有时不会完整生效。建议日常优先使用 H5 的 Vite 热更新快速调试，并定期在微信开发者工具中验证小程序端效果。
+
+### 4. 构建、预览和类型检查
+
+```sh
+# 生产微信小程序产物
+npm run build:wx
+
+# 生产 H5 产物
+npm run build:h5
+
+# 预览构建后的 H5 应用
+npm run preview:h5
+
+# 使用 tsgo 进行类型检查
+npm run typecheck
+```
+
+### 5. 使用 Taro 虚拟模块
+
+应用代码请使用这些导入：
+
+```tsx
+import Taro from 'virtual:taro/api'
+import { Text, View } from 'virtual:taro/components'
+```
+
+| 导入 | 用途 |
+| --- | --- |
+| `virtual:taro/components` | Taro React 组件，例如 `View`、`Text`、`Button`、`Image` 和 `ScrollView`。 |
+| `virtual:taro/api` | Taro API 和 hooks，例如 `Taro.navigateTo`、`Taro.getWindowInfo` 和 `Taro.useLaunch`。 |
+
+用法与 Taro 本身一致；组件和 API 的具体用法请参考 [Taro 官网](https://docs.taro.zone)。
+
+你不再需要安装 `@tarojs/*` 包；应用代码也不要从 `@tarojs/*` 导入。
+
+
+## 手动接入已有应用
+
+已有应用或自定义项目结构，可以按下面的步骤手动接入插件。先安装插件：
+
+```sh
+npm install -D vite-plugin-taro
+```
+
+你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 检查器，以及 Node/React 类型包。如果应用尚未安装它们，请安装缺失的包：
+
+```sh
+npm install react react-dom
+npm install -D vite @typescript/native-preview @types/node @types/react @types/react-dom
+```
+
+你不应再直接依赖任何 `@tarojs/*` 包。如果已经依赖，请将它们移除。
+
+下面的步骤会创建如下源码结构：
+
+```text
+my-app/
+├── index.html
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── src/
+    ├── app.css
+    ├── app.ts
+    └── pages/
+        └── index/
+            └── index.tsx
+```
+
+你也可以参考 [packages/loan-genius](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius) 中的示例布局。
+
+### 1. 添加 TypeScript 声明
+
+将插件客户端类型添加到 `tsconfig.json`，让 TypeScript 识别虚拟模块：
+
+```json
+{
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "moduleResolution": "bundler",
+        "types": ["vite/client", "vite-plugin-taro/client"]
+    },
+    "include": ["src"]
+}
+```
+
+### 2. 配置 Vite
+
+创建 `vite.config.ts`，并从环境变量中选择插件目标：
+
+```ts
+import { defineConfig, loadEnv } from 'vite'
+import vitePluginTaro, { type VitePluginTaroTarget } from 'vite-plugin-taro'
+
+const targetEnvName = 'VITE_PLUGIN_TARO_TARGET'
+
+function getTarget(env: Record<string, string>): VitePluginTaroTarget {
+    const target = env[targetEnvName]
+    if (target === 'wx' || target === 'h5') return target
+    throw new Error(`${targetEnvName} must be "wx" or "h5".`)
+}
+
+export default defineConfig(({ mode }) => {
+    const env = loadEnv(mode, process.cwd(), 'VITE_PLUGIN_TARO_')
+    const target = getTarget(env)
+
+    return {
+        build: {
+            outDir: `dist/${target}`
+        },
+        plugins: [
+            vitePluginTaro({
+                target,
+                app: 'src/app.ts',
+                pages: [
+                    {
+                        path: 'pages/index/index',
+                        config: {
+                            navigationBarTitleText: 'Home'
+                        }
+                    }
+                ],
+                appJson: {
+                    window: {
+                        navigationBarTitleText: 'Demo',
+                        navigationBarBackgroundColor: '#ffffff'
+                    }
+                },
+                projectConfigJson: {
+                    appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid',
+                    projectname: 'demo',
+                    compileType: 'miniprogram'
+                },
+                sitemapJson: {
+                    rules: [{ action: 'allow', page: '*' }]
+                }
+            })
+        ]
+    }
+})
+```
+
+重要约定：
+
+- 每次 Vite 运行时，`target` 必须是 `wx` 或 `h5`。
+- `app` 是 React 根应用组件模块，应默认导出应用组件。
+- 每个 `pages[].path` 都会映射到 `src/${path}.tsx` 文件。例如，`pages/index/index` 需要 `src/pages/index/index.tsx`。
+- `appJson.pages` 会根据 `pages` 自动生成；你在 `appJson` 中传入的任何 `pages` 字段都会被覆盖。
+- 插件不会读取 Taro CLI 配置文件，例如 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 文件。请通过插件选项传入应用和页面配置。
+
+### 3. 创建应用组件
+
+`src/app.ts` 是共享应用包装组件。它会通过 `children` 接收当前页面。
+
+```tsx
+import Taro from 'virtual:taro/api'
+import type { PropsWithChildren } from 'react'
+import './app.css'
+
+function App({ children }: PropsWithChildren) {
+    Taro.useLaunch(() => {
+        console.log('App launched')
+    })
+
+    return children
+}
+
+export default App
+```
+
+请在应用组件中导入全局样式。微信构建会将它们收集到 `app.wxss`，H5 输出也会包含它们。
+
+### 4. 创建页面组件
+
+`src/pages/index/index.tsx` 是 `pages/index/index` 对应的 React 页面组件。
+
+```tsx
+import Taro from 'virtual:taro/api'
+import { Button, Text, View } from 'virtual:taro/components'
+
+export default function IndexPage() {
+    const windowInfo = Taro.getWindowInfo()
+
+    return (
+        <View className="p-4">
+            <Text>Viewport width: {windowInfo.windowWidth}</Text>
+            <Button
+                onClick={() => {
+                    Taro.showToast({ title: 'Hello from Taro' })
+                }}
+            >
+                Show toast
+            </Button>
+        </View>
+    )
+}
+```
+
+### 5. 添加 H5 HTML 外壳
+
+对于 H5，请保留一个普通的 Vite `index.html`，并包含 `#app` 挂载节点。插件会自动注入生成的 Taro H5 入口，因此你不需要普通 Vite 的 `src/main.tsx` 脚本。
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Taro Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>
+```
+
+### 6. 添加脚本
+
+使用与 `create-vite-taro` 生成项目一致的脚本：
+
+```json
+{
+    "scripts": {
+        "dev:wx": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
+        "dev:h5": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:wx": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build",
+        "build:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite build",
+        "preview:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
+        "typecheck": "tsgo -b"
+    }
+}
+```
+
+在 Windows shell 中，请使用 `cross-env`。
+
+### 7. 运行每个目标
+
+```sh
+npm run dev:wx       # 以 watch 模式重新构建 dist/wx
+npm run dev:h5       # 启动 H5 开发服务器
+npm run build:wx     # 构建 dist/wx
+npm run build:h5     # 构建 dist/h5
+npm run preview:h5   # 预览 dist/h5
+npm run typecheck    # 使用 tsgo 进行类型检查
+```
+
+在微信开发者工具中打开生成的 `dist/wx` 目录。
+
+| 目标 | 含义 | 输出目录 |
+| --- | --- | --- |
+| `wx` | 开发/生产模式下的微信小程序。 | `dist/wx` |
+| `h5` | H5 生产输出。 | `dist/h5` |
+
+## 选项
+
+```ts
+type VitePluginTaroTarget = 'wx' | 'h5'
+
+type VitePluginTaroPageOption = {
+    path: string
+    config: Record<string, unknown>
+}
+
+type VitePluginTaroOptions = {
+    target: VitePluginTaroTarget
+    app: string
+    pages: VitePluginTaroPageOption[]
+    appJson: Record<string, unknown>
+    projectConfigJson: Record<string, unknown>
+    sitemapJson: Record<string, unknown>
+}
+```
+
+| 选项 | 描述 |
+| --- | --- |
+| `target` | 本次 Vite 调用的活动目标。微信小程序使用 `wx`，Web 使用 `h5`。 |
+| `app` | 默认导出根 React 应用组件的源码文件，例如 `src/app.ts` 或 `src/app.tsx`。 |
+| `pages` | 有序页面列表。该顺序会成为 `app.json.pages` 和 H5 路由顺序。 |
+| `pages[].path` | 不带扩展名的 Taro 风格路由和输出路径，例如 `pages/index/index`。页面组件必须存在于 `src/${path}.tsx`。 |
+| `pages[].config` | 合并到生成的微信页面 JSON 和 H5 路由配置中的页面配置。 |
+| `appJson` | 基础应用配置。插件会用 `options.pages` 覆盖其中的 `pages` 字段。 |
+| `projectConfigJson` | `wx` 构建时输出的微信 `project.config.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
+| `sitemapJson` | `wx` 构建时输出的微信 `sitemap.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
+
+## 样式
+
+你可以使用普通 CSS、CSS Modules 或 Tailwind CSS v4。
+
+对于 Tailwind CSS v4，请从全局 CSS 文件（例如 `src/app.css`）导入 Tailwind：
+
+```css
+@import "tailwindcss/theme.css";
+@import "tailwindcss/preflight.css";
+@import "tailwindcss/utilities.css";
+
+@source "./";
+```
+
+插件会为 `wx` 构建注册 `weapp-tailwindcss`，并为 `h5` 构建注册 `@tailwindcss/vite`。对于 `wx`，Vite 输出的 CSS 会被收集到 `app.wxss`，并为每个页面生成配套的 `.wxss` 文件。
+
+## 条件编译
+
+插件会在 Vite 解析源码前移除未激活的 Taro 风格条件注释块。它适用于 `node_modules` 之外的 TypeScript、JavaScript、JSX/TSX、CSS、Sass、Less 和 Stylus 文件。
+
+```ts
+// #ifdef wx
+console.log('WeChat only')
+// #endif
+
+// #ifdef h5
+console.log('H5 only')
+// #endif
+
+// #if wx && !h5
+console.log('WeChat expression')
+// #elif h5
+console.log('H5 expression')
+// #else
+console.log('fallback')
+// #endif
+```
+
+支持的指令包括 `#ifdef`、`#ifndef`、`#if`、`#elif`、`#else` 和 `#endif`。条件使用插件目标标记 `wx` 和 `h5`；`#if` 表达式支持 `!`、`&&` 和 `||`。
+
+## 按目标输出
+
+### 微信小程序
+
+对于 `target: 'wx'`，插件会配置 Vite，输出微信兼容的 CommonJS chunk 和小程序配套文件。
+
+典型输出：
+
+```text
+dist/wx/
+├── app.js
+├── app.json
+├── app.wxss
+├── base.wxml
+├── comp.js
+├── comp.json
+├── comp.wxml
+├── project.config.json
+├── sitemap.json
+├── utils.wxs
+└── pages/**
+```
+
+请使用微信开发者工具打开 `dist/wx`；不要打开源码项目目录。
+
+### H5
+
+对于 `target: 'h5'`，插件会向 `index.html` 注入生成模块，导入 Taro 的 H5 组件样式，根据 `pages` 构建路由记录，并使用 Taro 的 hash-history 路由挂载应用。路由使用配置中的页面路径，例如 `#/pages/index/index`。
+
+## 从 Taro 迁移
+
+你可以保留大多数 React 页面组件、业务逻辑、资源和样式，但构建入口会从 Taro CLI 配置迁移到 Vite 配置。
+
+迁移清单：
+
+1. 安装 `vite-plugin-taro`，并创建包含 `vitePluginTaro(...)` 的 `vite.config.ts`。
+2. 将应用配置和页面配置移到 `vite.config.ts` 中。插件不会读取 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 等 Taro 文件。
+3. 在 `pages` 中注册每个页面。每个页面路径都必须匹配 `src/${path}.tsx`。
+4. 将 Taro 脚本替换为设置 `VITE_PLUGIN_TARO_TARGET=wx` 或 `VITE_PLUGIN_TARO_TARGET=h5` 的 Vite 脚本。
+5. 对于 H5，添加普通 Vite `index.html`，其中包含 `<div id="app"></div>`，且不要添加单独的 `src/main.tsx` 入口。
+6. 将应用代码中的 `@tarojs/*` 导入替换为插件虚拟模块。
+
+迁移前：
+
+```tsx
+import Taro from '@tarojs/taro'
+import { Text, View } from '@tarojs/components'
+```
+
+迁移后：
+
+```tsx
+import Taro from 'virtual:taro/api'
+import { Text, View } from 'virtual:taro/components'
+```
+
+应用代码中禁止直接导入 `@tarojs/*`。请让插件负责 Taro 运行时解析，使微信和 H5 构建都获得正确的目标特定别名。
+
+## 示例应用
+
+示例应用位于 [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius)。它展示了页面约定、目标选择、微信输出、H5 路由和 Tailwind 样式。
+
+```sh
+git clone https://github.com/sep2/vite-plugin-taro.git
+
+# 安装依赖
+pnpm install
+
+# 首次运行，生成打过补丁的 Taro 包
+pnpm prepare:taro
+
+# 构建插件，供示例应用使用
+pnpm build:plugin
+
+# 运行微信示例应用
+pnpm dev:sample:wx
+
+# 将示例应用构建为微信输出
+pnpm build:sample:wx
+
+# 以开发模式运行 H5 示例应用
+pnpm dev:sample:h5
+
+# 将示例应用构建为 H5 输出并预览
+pnpm build:sample:h5
+pnpm preview:sample:h5
+```
+
+使用微信开发者工具打开 `packages/loan-genius/dist/wx`，以测试小程序输出。
+
+## 开发本仓库
+
+```sh
+pnpm install
+pnpm prepare:taro
+pnpm build:plugin
+pnpm typecheck
+```
+
+常用脚本：
+
+| 脚本 | 描述 |
+| --- | --- |
+| `pnpm prepare:taro` | 从上游 npm tarball 和本地 patch 文件重新生成打过补丁的 React 19 Taro 包。 |
+| `pnpm build:plugin` | 将 `packages/vite-plugin-taro` 构建到 `dist`。 |
+| `pnpm typecheck` | 使用 `tsgo` 对插件和示例应用进行类型检查。 |
+| `pnpm lint` | 运行 Biome 检查。 |
+| `pnpm format` | 应用 Biome 格式化。 |
+| `pnpm dev:sample:wx` | 以 watch 模式构建微信小程序示例。请先构建插件。 |
+| `pnpm dev:sample:h5` | 以 Vite 开发模式启动 H5 示例应用。请先构建插件。 |
+| `pnpm build:sample:wx` | 将微信小程序示例构建到 `packages/loan-genius/dist/wx`。 |
+| `pnpm build:sample:h5` | 将 H5 示例应用构建到 `packages/loan-genius/dist/h5`。 |
+| `pnpm preview:sample:h5` | 预览构建后的 H5 示例。 |
+| `pnpm publish:dry` | 干运行包校验和发布流程。 |
+| `pnpm release <version\|bump>` | 验证发布、更新版本、创建 release commit 和 tag，并推送触发 CI 发布。 |
+| `pnpm publish:all` | 按依赖顺序发布公开包；主要由基于 tag 的 Trusted Publishing 工作流调用。 |
+
+## 限制
+
+- 目前只生成 `wx` 和 `h5` 目标。
+- 应用代码不能直接导入 `@tarojs/*` 包。
+
+## 排查问题
+
+| 问题 | 检查项 |
+| --- | --- |
+| `VITE_PLUGIN_TARO_TARGET must be "wx" or "h5"` | 在脚本或 `.env` 文件中设置目标环境变量。 |
+| `pnpm install` 提示忽略了依赖构建脚本 | 运行 `pnpm approve-builds`，按提示批准需要构建的依赖。 |
+| 页面无法解析 | 确认 `pages[].path` 有匹配的 `src/${path}.tsx` 文件。 |
+| 微信开发者工具无法打开应用 | 打开生成的 `dist/wx` 文件夹，并检查 `projectConfigJson.appid`。 |
+| H5 显示空白页 | 确保 `index.html` 中保留 `<div id="app"></div>`，已注册插件，并避免添加单独的默认 Vite `main.tsx` 入口。 |
+| Taro API 缺失或行为不同 | 移除应用代码中直接导入的 `@tarojs/*`，并从 `virtual:taro/api` 导入 Taro。 |
+| 组件在 H5 上渲染时缺少预期样式 | 从 `virtual:taro/components` 导入组件，并确保 `h5` 目标启用了插件。 |
+| Tailwind 类没有生效 | 确保全局 CSS 导入 Tailwind，并包含覆盖源码文件的 `@source` 路径。 |
+
+## 发布流程
+
+本仓库使用 npm Trusted Publishing 和 GitHub Actions 自动发布。普通推送到 `main` 不会发布；只有推送匹配 `v*.*.*` 的 tag 才会触发 `.github/workflows/publish.yml`。
+
+创建发布：
+
+```sh
+pnpm release patch
+```
+
+`pnpm release` 会要求干净的 `main` 工作区，运行 `pnpm version:bump`，执行 `pnpm publish:dry -- --no-git-check` 验证，创建 `chore: release vX.Y.Z` commit 和 `vX.Y.Z` tag，然后推送 branch 与 tag 触发 CI。也可以发布精确版本或预发布版本：
+
+```sh
+pnpm release 0.2.0
+pnpm release prerelease --preid beta
+pnpm release patch --dry-run
+pnpm release patch --no-push
+```
+
+CI 会运行 `pnpm publish:all -- --no-git-check`，按依赖顺序打包并通过 npm OIDC 发布公开包。不要为发布工作流配置 `NPM_TOKEN`；每个 npm 包的 Trusted Publisher 应指向 `publish.yml`。
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -32,7 +32,8 @@
     "client.d.ts",
     "LICENSE",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "README.zh.md"
   ],
   "keywords": [
     "vite",
@@ -64,8 +65,8 @@
     "babel-plugin-transform-taroapi": "^4.2.0",
     "tailwindcss": "^4.3.1",
     "weapp-tailwindcss": "^5.0.13",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.6",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.1.6"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.8",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.1.8"
   },
   "peerDependencies": {
     "react": "^19.0.0",