From a20dc071306250a6f883728a641e03bb5c926aed Mon Sep 17 00:00:00 2001
From: cnguu <www@cnguu.cn>
Date: Sat, 6 Sep 2025 14:27:32 +0800
Subject: [PATCH 1/4] =?UTF-8?q?feat:=20=E5=A2=9E=E5=8A=A0=E8=BF=87?=
 =?UTF-8?q?=E6=BB=A4=E9=A1=B5=E9=9D=A2=E9=92=A9=E5=AD=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore                      |  3 ++-
 README.md                       | 31 ++++++++++++++++++++++++
 examples/src/pages.json         |  6 +++++
 examples/src/pages/excluded.vue | 42 +++++++++++++++++++++++++++++++++
 examples/vite.config.ts         |  3 +++
 src/index.ts                    | 10 ++++++--
 src/utils.ts                    |  2 +-
 7 files changed, 93 insertions(+), 4 deletions(-)
 create mode 100644 examples/src/pages/excluded.vue

diff --git a/.gitignore b/.gitignore
index 1058fbd..eb9553b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,4 +3,5 @@ node_modules
 
 # Build Outputs
 build
-dist
\ No newline at end of file
+dist
+.idea
diff --git a/README.md b/README.md
index a736a7d..d824d30 100644
--- a/README.md
+++ b/README.md
@@ -494,6 +494,37 @@ function showToast() {
 
 </details>
 
+<details>
+
+<summary>
+  <strong>(点击展开) 示例四：过滤不需要根组件的页面</strong>
+</summary>
+<br />
+
+> 总会有一些不需要根组件的页面，这时候可以通过 `filterPage` 选项来过滤
+
+```ts
+// vite.config.(js|ts)
+
+import Uni from '@dcloudio/vite-plugin-uni'
+import UniKuRoot from '@uni-ku/root'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    UniKuRoot({
+      // filterPage?: (pagePaths: string[]) => string[]
+      filterPage(pagePaths) {
+        return pagePaths.filter(path => !path.includes('excluded.vue'))
+      },
+    }),
+    Uni()
+  ]
+})
+```
+
+</details>
+
 ### 📝 待办
 
 - [x] 支持热更新
diff --git a/examples/src/pages.json b/examples/src/pages.json
index 7d00edb..a7e4e19 100644
--- a/examples/src/pages.json
+++ b/examples/src/pages.json
@@ -17,6 +17,12 @@
       "style": {
         "navigationBarTitleText": "uni-app"
       }
+    },
+    {
+      "path": "pages/excluded",
+      "style": {
+        "navigationBarTitleText": "uni-app"
+      }
     }
   ],
   "globalStyle": {
diff --git a/examples/src/pages/excluded.vue b/examples/src/pages/excluded.vue
new file mode 100644
index 0000000..110aa7d
--- /dev/null
+++ b/examples/src/pages/excluded.vue
@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import { useToast } from '@/composables/useToast'
+import LayoutDefault from '@/layouts/default.vue'
+import { onMounted, ref } from 'vue'
+
+const { globalToastState, showToast, hideToast } = useToast()
+
+function handleClick() {
+  return globalToastState.value ? hideToast() : showToast()
+}
+
+const uniKuRoot = ref()
+
+onMounted(() => {
+  // eslint-disable-next-line no-console
+  console.log(uniKuRoot.value?.exposeRef)
+})
+
+const color = 'red'
+</script>
+
+<template root="uniKuRoot">
+  <LayoutDefault>
+    <!-- 这行代码仅小程序可见，完全支持 PageMeta -->
+
+    <view>
+      Hello KuRoot
+    </view>
+    <view class="text">
+      Hello v-bind css
+    </view>
+    <button @click="handleClick">
+      展示Toast
+    </button>
+  </LayoutDefault>
+</template>
+
+<style scoped>
+.text {
+  color: v-bind(color)
+}
+</style>
diff --git a/examples/vite.config.ts b/examples/vite.config.ts
index fca8dca..65900d4 100644
--- a/examples/vite.config.ts
+++ b/examples/vite.config.ts
@@ -12,6 +12,9 @@ export default defineConfig({
     UniKuRoot({
       enabledVirtualHost: false,
       rootFileName: 'KuRoot',
+      filterPage(pagePaths) {
+        return pagePaths.filter(path => !path.includes('excluded.vue'))
+      },
     }),
     Uni(),
   ],
diff --git a/src/index.ts b/src/index.ts
index ab99f78..daeefc3 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -28,6 +28,10 @@ interface UniKuRootOptions {
    * @default 'App.ku'
    */
   rootFileName?: string
+  /**
+   * 页面过滤钩子
+   */
+  filterPage?: (pagePaths: string[]) => string[]
 }
 
 export default function UniKuRoot(options: UniKuRootOptions = {
@@ -37,7 +41,8 @@ export default function UniKuRoot(options: UniKuRootOptions = {
   const appKuPath = resolve(rootPath, `${options.rootFileName}.vue`)
   const pagesPath = resolve(rootPath, 'pages.json')
 
-  let pagesJson = loadPagesJson(pagesPath, rootPath)
+  let rawPagesJson = loadPagesJson(pagesPath, rootPath)
+  let pagesJson = options.filterPage ? options.filterPage(rawPagesJson) : rawPagesJson
 
   let watcher: FSWatcher | null = null
 
@@ -52,7 +57,8 @@ export default function UniKuRoot(options: UniKuRootOptions = {
     buildStart() {
       watcher = chokidar.watch(pagesPath).on('all', (event) => {
         if (['add', 'change'].includes(event)) {
-          pagesJson = loadPagesJson(pagesPath, rootPath)
+          rawPagesJson = loadPagesJson(pagesPath, rootPath)
+          pagesJson = options.filterPage ? options.filterPage(rawPagesJson) : rawPagesJson
         }
       })
     },
diff --git a/src/utils.ts b/src/utils.ts
index ddf6d20..0762805 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -22,7 +22,7 @@ export function formatPagePath(root: string, path: string) {
   return normalizePath(`${join(root, path)}.vue`)
 }
 
-export function loadPagesJson(path: string, rootPath: string) {
+export function loadPagesJson(path: string, rootPath: string): string[] {
   const pagesJsonRaw = readFileSync(path, 'utf-8')
 
   const { pages = [], subPackages = [] } = jsonParse(pagesJsonRaw)

From e37552aa32eca0347e963f8491a5b6dc8e39f717 Mon Sep 17 00:00:00 2001
From: cnguu <www@cnguu.cn>
Date: Sat, 6 Sep 2025 15:56:31 +0800
Subject: [PATCH 2/4] =?UTF-8?q?feat:=20=E8=BF=87=E6=BB=A4=E9=A1=B5?=
 =?UTF-8?q?=E9=9D=A2=E4=BD=BF=E7=94=A8exclude=E5=AE=9E=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md               |  9 ++++-----
 examples/vite.config.ts |  4 +---
 src/index.ts            | 14 ++++++--------
 3 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index d824d30..2abc845 100644
--- a/README.md
+++ b/README.md
@@ -501,7 +501,9 @@ function showToast() {
 </summary>
 <br />
 
-> 总会有一些不需要根组件的页面，这时候可以通过 `filterPage` 选项来过滤
+总会有一些不需要根组件的页面，这时候可以通过 `exclude` 选项来过滤
+
+> 注意：`exclude` 选项支持 glob 模式，等同于 [createFilter](https://cn.vite.dev/guide/api-plugin.html#filtering-include-exclude-pattern)
 
 ```ts
 // vite.config.(js|ts)
@@ -513,10 +515,7 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   plugins: [
     UniKuRoot({
-      // filterPage?: (pagePaths: string[]) => string[]
-      filterPage(pagePaths) {
-        return pagePaths.filter(path => !path.includes('excluded.vue'))
-      },
+      exclude: '**/excluded.vue'
     }),
     Uni()
   ]
diff --git a/examples/vite.config.ts b/examples/vite.config.ts
index 65900d4..dc9d7e6 100644
--- a/examples/vite.config.ts
+++ b/examples/vite.config.ts
@@ -12,9 +12,7 @@ export default defineConfig({
     UniKuRoot({
       enabledVirtualHost: false,
       rootFileName: 'KuRoot',
-      filterPage(pagePaths) {
-        return pagePaths.filter(path => !path.includes('excluded.vue'))
-      },
+      exclude: '**/excluded.vue',
     }),
     Uni(),
   ],
diff --git a/src/index.ts b/src/index.ts
index daeefc3..a02dcb9 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,6 +1,6 @@
 import type { MagicString } from '@vue/compiler-sfc'
 import type { FSWatcher } from 'chokidar'
-import type { Plugin } from 'vite'
+import type { FilterPattern, Plugin } from 'vite'
 
 import { resolve } from 'node:path'
 import process from 'node:process'
@@ -29,9 +29,9 @@ interface UniKuRootOptions {
    */
   rootFileName?: string
   /**
-   * 页面过滤钩子
+   * 需要排除的路径模式（glob 格式）
    */
-  filterPage?: (pagePaths: string[]) => string[]
+  exclude?: FilterPattern
 }
 
 export default function UniKuRoot(options: UniKuRootOptions = {
@@ -41,8 +41,7 @@ export default function UniKuRoot(options: UniKuRootOptions = {
   const appKuPath = resolve(rootPath, `${options.rootFileName}.vue`)
   const pagesPath = resolve(rootPath, 'pages.json')
 
-  let rawPagesJson = loadPagesJson(pagesPath, rootPath)
-  let pagesJson = options.filterPage ? options.filterPage(rawPagesJson) : rawPagesJson
+  let pagesJson = loadPagesJson(pagesPath, rootPath)
 
   let watcher: FSWatcher | null = null
 
@@ -57,8 +56,7 @@ export default function UniKuRoot(options: UniKuRootOptions = {
     buildStart() {
       watcher = chokidar.watch(pagesPath).on('all', (event) => {
         if (['add', 'change'].includes(event)) {
-          rawPagesJson = loadPagesJson(pagesPath, rootPath)
-          pagesJson = options.filterPage ? options.filterPage(rawPagesJson) : rawPagesJson
+          pagesJson = loadPagesJson(pagesPath, rootPath)
         }
       })
     },
@@ -77,7 +75,7 @@ export default function UniKuRoot(options: UniKuRootOptions = {
 
       const pageId = hasPlatformPlugin ? normalizePlatformPath(id) : id
 
-      const filterPage = createFilter(pagesJson)
+      const filterPage = createFilter(pagesJson, options.exclude)
       if (filterPage(pageId)) {
         ms = await transformPage(code, options.enabledGlobalRef)
       }

From 9d85216ce3bbfa799096411ca625f4270688bd0e Mon Sep 17 00:00:00 2001
From: Skiyee <319619193@qq.com>
Date: Sat, 6 Sep 2025 20:37:41 +0800
Subject: [PATCH 3/4] =?UTF-8?q?chore:=20=E4=BD=BF=E7=94=A8=E6=9B=B4?=
 =?UTF-8?q?=E5=8A=A0=E6=98=8E=E6=98=BE=E7=9A=84=E5=91=BD=E5=90=8D=E4=BB=A5?=
 =?UTF-8?q?=E5=8F=8A=E6=B3=A8=E9=87=8A=E4=BF=A1=E6=81=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 examples/vite.config.ts |  2 +-
 src/index.ts            | 10 +++++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/examples/vite.config.ts b/examples/vite.config.ts
index dc9d7e6..37861c5 100644
--- a/examples/vite.config.ts
+++ b/examples/vite.config.ts
@@ -12,7 +12,7 @@ export default defineConfig({
     UniKuRoot({
       enabledVirtualHost: false,
       rootFileName: 'KuRoot',
-      exclude: '**/excluded.vue',
+      excludePages: 'src/pages/excluded.vue',
     }),
     Uni(),
   ],
diff --git a/src/index.ts b/src/index.ts
index a02dcb9..e8616fe 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -29,9 +29,13 @@ interface UniKuRootOptions {
    */
   rootFileName?: string
   /**
-   * 需要排除的路径模式（glob 格式）
+   * 需要排除根组件的页面，支持 glob 匹配
+   * @example
+   * ```
+   * ['src/pages/some.vue', 'src/exclude/*.vue']
+   * ```
    */
-  exclude?: FilterPattern
+  excludePages?: FilterPattern
 }
 
 export default function UniKuRoot(options: UniKuRootOptions = {
@@ -75,7 +79,7 @@ export default function UniKuRoot(options: UniKuRootOptions = {
 
       const pageId = hasPlatformPlugin ? normalizePlatformPath(id) : id
 
-      const filterPage = createFilter(pagesJson, options.exclude)
+      const filterPage = createFilter(pagesJson, options.excludePages)
       if (filterPage(pageId)) {
         ms = await transformPage(code, options.enabledGlobalRef)
       }

From 39c6c3fd314f3ac82d720ed86861a7c7c6152c74 Mon Sep 17 00:00:00 2001
From: Skiyee <319619193@qq.com>
Date: Sun, 7 Sep 2025 14:06:38 +0800
Subject: [PATCH 4/4] =?UTF-8?q?chore(docs):=20=E6=9B=B4=E6=94=B9=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E8=87=B3=E6=AD=A3=E7=A1=AE=E5=8C=BA=E5=9F=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 63 +++++++++++++++++++++++++++++--------------------------
 1 file changed, 33 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 2abc845..ecd9502 100644
--- a/README.md
+++ b/README.md
@@ -251,6 +251,39 @@ onMounted(() => {
 
 </details>
 
+<details>
+
+<summary>
+  <strong>(点击展开) 功能三：过滤掉不需要根组件的页面</strong>
+</summary>
+<br />
+
+如果遇到一些不需要根组件的页面，可以设置 `excludePages` 选项来过滤
+
+> `excludePages` 选项支持采用 glob 模式进行编写
+
+```ts
+// vite.config.(js|ts)
+
+import Uni from '@dcloudio/vite-plugin-uni'
+import UniKuRoot from '@uni-ku/root'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    UniKuRoot({
+      excludePages: [
+        'src/exclude.vue',
+        'src/exclude/**/*.vue'
+      ],
+    }),
+    Uni()
+  ]
+})
+```
+
+</details>
+
 ### ✨ 例子
 
 > [!TIP]
@@ -494,36 +527,6 @@ function showToast() {
 
 </details>
 
-<details>
-
-<summary>
-  <strong>(点击展开) 示例四：过滤不需要根组件的页面</strong>
-</summary>
-<br />
-
-总会有一些不需要根组件的页面，这时候可以通过 `exclude` 选项来过滤
-
-> 注意：`exclude` 选项支持 glob 模式，等同于 [createFilter](https://cn.vite.dev/guide/api-plugin.html#filtering-include-exclude-pattern)
-
-```ts
-// vite.config.(js|ts)
-
-import Uni from '@dcloudio/vite-plugin-uni'
-import UniKuRoot from '@uni-ku/root'
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  plugins: [
-    UniKuRoot({
-      exclude: '**/excluded.vue'
-    }),
-    Uni()
-  ]
-})
-```
-
-</details>
-
 ### 📝 待办
 
 - [x] 支持热更新