mp-weixin-back 0.0.15 → 0.0.16

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Create Release Pull Request or Publish
+        uses: changesets/action@v1
+        with:
+          publish: pnpm release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/client.d.ts

@@ -1,32 +1,109 @@
 declare module 'mp-weixin-back-helper' {
-  type Config = {
+  /**
+   * Per-page options for `onPageBack()`.
+   */
+  type OnPageBackOptions = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
      */
-    initialValue: boolean
+    preventDefault?: boolean
+
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
      */
-    preventDefault: boolean
+    frequency?: number
+
     /**
-     * 阻止次数，默认是 `1`
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` and call `activeMpBack()` manually to enable later.
+     * @default true
      */
-    frequency: number
+    initialValue?: boolean
   }
 
-  function onPageBack(callback: () => void, params?: Partial<Config>)
+  /**
+   * Listen to back navigation events (gesture back + navbar back button) on the current page.
+   *
+   * Must be called inside `<script setup>` at the top level.
+   *
+   * @param callback - Function to call when back navigation is detected.
+   * @param options - Optional per-page configuration. Overrides global plugin config.
+   *
+   * @example
+   * // Basic usage
+   * import onPageBack from 'mp-weixin-back-helper'
+   *
+   * onPageBack(() => {
+   *   console.log('back detected')
+   * })
+   *
+   * @example
+   * // Prevent back and show a confirmation dialog
+   * import onPageBack from 'mp-weixin-back-helper'
+   *
+   * onPageBack(
+   *   () => {
+   *     uni.showModal({
+   *       title: '提示',
+   *       content: '确定要返回吗？',
+   *       success: (res) => {
+   *         if (res.confirm) uni.navigateBack()
+   *       },
+   *     })
+   *   },
+   *   { preventDefault: true }
+   * )
+   *
+   * @example
+   * // Start disabled, enable after a button click
+   * import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
+   *
+   * onPageBack(() => { handleBack() }, { initialValue: false })
+   *
+   * function startListening() { activeMpBack() }
+   * function stopListening() { inactiveMpBack() }
+   */
+  function onPageBack(callback: () => void, options?: OnPageBackOptions): void
 
   /**
-   * 开启监听手势滑动事件
+   * Enable the back event listener for the current page.
+   *
+   * Use when `initialValue: false` was passed to `onPageBack()`,
+   * or to re-enable after calling `inactiveMpBack()`.
+   *
+   * Must be called inside `<script setup>`.
+   *
+   * @example
+   * import { activeMpBack } from 'mp-weixin-back-helper'
+   *
+   * // Enable on button click
+   * function handleEnable() {
+   *   activeMpBack()
+   * }
    */
-  function activeMpBack()
+  function activeMpBack(): void
 
   /**
-   * 禁用监听手势滑动事件
+   * Disable the back event listener for the current page.
+   *
+   * The page will resume its default back behavior until `activeMpBack()` is called again.
+   *
+   * Must be called inside `<script setup>`.
+   *
+   * @example
+   * import { inactiveMpBack } from 'mp-weixin-back-helper'
+   *
+   * // Disable when a modal is open
+   * function handleModalOpen() {
+   *   inactiveMpBack()
+   * }
    */
-  function inactiveMpBack()
+  function inactiveMpBack(): void
 
   export default onPageBack
-
   export { activeMpBack, inactiveMpBack }
 }

package/dist/index.cjs

@@ -423,9 +423,10 @@ async function resolveCompiler(root) {
         return await import('@vue/compiler-sfc');
       } catch (secondError) {
         throw new Error(
-          `\u65E0\u6CD5\u89E3\u6790 @vue/compiler-sfc\u3002
-\u6B64\u63D2\u4EF6\u9700\u8981\u9879\u76EE\u4E2D\u5B89\u88C5 @vue/compiler-sfc\u3002
-\u8BF7\u624B\u52A8\u5B89\u88C5\uFF1Apnpm add -D @vue/compiler-sfc
+          `[mp-weixin-back] Cannot resolve @vue/compiler-sfc.
+This plugin requires @vue/compiler-sfc to be installed in your project.
+Fix: pnpm add -D @vue/compiler-sfc
+Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E
 `
         );
       }
@@ -447,7 +448,10 @@ async function transformVueFile(code, id) {
     const walker = scriptSetup ? "compositionWalk" : "optionsWalk";
     return vueWalker[walker](this, code, sfc, id);
   } catch (error) {
-    this.log.error("\u89E3\u6790vue\u6587\u4EF6\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u662F\u5426\u6B63\u786E");
+    this.log.error(
+      `Failed to transform ${id}. Please check the file is a valid Vue SFC.
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#-\u5FEB\u901F\u5F00\u59CB`
+    );
     this.log.error(String(error));
     return code;
   }
@@ -511,7 +515,11 @@ class pageContext {
         }
       }
     } catch (error) {
-      this.log.error("\u8BFB\u53D6pages.json\u6587\u4EF6\u5931\u8D25");
+      this.log.error(
+        `Failed to read pages.json. Make sure src/pages.json exists and is valid JSON/JSON5.
+  Path checked: ${this.getPagesJsonPath()}
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E`
+      );
       this.log.debugLog(String(error));
     }
   }

package/dist/index.d.cts

@@ -1,34 +1,67 @@
 import { Plugin } from 'vite';
 
-type UserOptions = Partial<Config>;
-type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+type BackParams = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * The path of the current page that triggered the back event.
+     * @example 'pages/index/index'
      */
-    initialValue: boolean;
+    page: string;
+};
+/**
+ * Per-page options for `onPageBack()`.
+ */
+type OnPageBackOptions = {
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
+     * @example
+     * onPageBack(() => showDialog(), { preventDefault: true })
      */
     preventDefault: boolean;
     /**
-     * 阻止次数，默认是 `1`
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
+     * @example
+     * // Block 3 times, then allow back
+     * onPageBack(() => {}, { frequency: 3 })
      */
     frequency: number;
     /**
-     * 调试模式
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+     * @default true
+     * @example
+     * // Start disabled, enable after user action
+     * onPageBack(() => {}, { initialValue: false })
+     * activeMpBack()
      */
-    debug: boolean;
+    initialValue: boolean;
+};
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+type Config = OnPageBackOptions & {
     /**
-     * 页面回退时触发
+     * Enable debug logging in development mode.
+     * @default false
      */
-    onPageBack?: (params: BackParams) => void;
-};
-type BackParams = {
+    debug: boolean;
     /**
-     * 当前页面路径
+     * Global callback fired every time a back event is detected on any page.
+     * Page-level callbacks registered via `onPageBack()` run in addition to this.
+     * @example
+     * mpBackPlugin({
+     *   onPageBack: ({ page }) => console.log('back on:', page)
+     * })
      */
-    page: string;
+    onPageBack?: (params: BackParams) => void;
 };
+type UserOptions = Partial<Config>;
 
 declare function MpBackPlugin(userOptions?: UserOptions): Plugin;
 

package/dist/index.d.mts

@@ -1,34 +1,67 @@
 import { Plugin } from 'vite';
 
-type UserOptions = Partial<Config>;
-type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+type BackParams = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * The path of the current page that triggered the back event.
+     * @example 'pages/index/index'
      */
-    initialValue: boolean;
+    page: string;
+};
+/**
+ * Per-page options for `onPageBack()`.
+ */
+type OnPageBackOptions = {
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
+     * @example
+     * onPageBack(() => showDialog(), { preventDefault: true })
      */
     preventDefault: boolean;
     /**
-     * 阻止次数，默认是 `1`
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
+     * @example
+     * // Block 3 times, then allow back
+     * onPageBack(() => {}, { frequency: 3 })
      */
     frequency: number;
     /**
-     * 调试模式
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+     * @default true
+     * @example
+     * // Start disabled, enable after user action
+     * onPageBack(() => {}, { initialValue: false })
+     * activeMpBack()
      */
-    debug: boolean;
+    initialValue: boolean;
+};
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+type Config = OnPageBackOptions & {
     /**
-     * 页面回退时触发
+     * Enable debug logging in development mode.
+     * @default false
      */
-    onPageBack?: (params: BackParams) => void;
-};
-type BackParams = {
+    debug: boolean;
     /**
-     * 当前页面路径
+     * Global callback fired every time a back event is detected on any page.
+     * Page-level callbacks registered via `onPageBack()` run in addition to this.
+     * @example
+     * mpBackPlugin({
+     *   onPageBack: ({ page }) => console.log('back on:', page)
+     * })
      */
-    page: string;
+    onPageBack?: (params: BackParams) => void;
 };
+type UserOptions = Partial<Config>;
 
 declare function MpBackPlugin(userOptions?: UserOptions): Plugin;
 

package/dist/index.d.ts

@@ -1,34 +1,67 @@
 import { Plugin } from 'vite';
 
-type UserOptions = Partial<Config>;
-type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+type BackParams = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * The path of the current page that triggered the back event.
+     * @example 'pages/index/index'
      */
-    initialValue: boolean;
+    page: string;
+};
+/**
+ * Per-page options for `onPageBack()`.
+ */
+type OnPageBackOptions = {
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
+     * @example
+     * onPageBack(() => showDialog(), { preventDefault: true })
      */
     preventDefault: boolean;
     /**
-     * 阻止次数，默认是 `1`
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
+     * @example
+     * // Block 3 times, then allow back
+     * onPageBack(() => {}, { frequency: 3 })
      */
     frequency: number;
     /**
-     * 调试模式
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+     * @default true
+     * @example
+     * // Start disabled, enable after user action
+     * onPageBack(() => {}, { initialValue: false })
+     * activeMpBack()
      */
-    debug: boolean;
+    initialValue: boolean;
+};
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+type Config = OnPageBackOptions & {
     /**
-     * 页面回退时触发
+     * Enable debug logging in development mode.
+     * @default false
      */
-    onPageBack?: (params: BackParams) => void;
-};
-type BackParams = {
+    debug: boolean;
     /**
-     * 当前页面路径
+     * Global callback fired every time a back event is detected on any page.
+     * Page-level callbacks registered via `onPageBack()` run in addition to this.
+     * @example
+     * mpBackPlugin({
+     *   onPageBack: ({ page }) => console.log('back on:', page)
+     * })
      */
-    page: string;
+    onPageBack?: (params: BackParams) => void;
 };
+type UserOptions = Partial<Config>;
 
 declare function MpBackPlugin(userOptions?: UserOptions): Plugin;
 

package/dist/index.mjs

@@ -412,9 +412,10 @@ async function resolveCompiler(root) {
         return await import('@vue/compiler-sfc');
       } catch (secondError) {
         throw new Error(
-          `\u65E0\u6CD5\u89E3\u6790 @vue/compiler-sfc\u3002
-\u6B64\u63D2\u4EF6\u9700\u8981\u9879\u76EE\u4E2D\u5B89\u88C5 @vue/compiler-sfc\u3002
-\u8BF7\u624B\u52A8\u5B89\u88C5\uFF1Apnpm add -D @vue/compiler-sfc
+          `[mp-weixin-back] Cannot resolve @vue/compiler-sfc.
+This plugin requires @vue/compiler-sfc to be installed in your project.
+Fix: pnpm add -D @vue/compiler-sfc
+Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E
 `
         );
       }
@@ -436,7 +437,10 @@ async function transformVueFile(code, id) {
     const walker = scriptSetup ? "compositionWalk" : "optionsWalk";
     return vueWalker[walker](this, code, sfc, id);
   } catch (error) {
-    this.log.error("\u89E3\u6790vue\u6587\u4EF6\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u662F\u5426\u6B63\u786E");
+    this.log.error(
+      `Failed to transform ${id}. Please check the file is a valid Vue SFC.
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#-\u5FEB\u901F\u5F00\u59CB`
+    );
     this.log.error(String(error));
     return code;
   }
@@ -500,7 +504,11 @@ class pageContext {
         }
       }
     } catch (error) {
-      this.log.error("\u8BFB\u53D6pages.json\u6587\u4EF6\u5931\u8D25");
+      this.log.error(
+        `Failed to read pages.json. Make sure src/pages.json exists and is valid JSON/JSON5.
+  Path checked: ${this.getPagesJsonPath()}
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E`
+      );
       this.log.debugLog(String(error));
     }
   }

package/llms.txt

@@ -0,0 +1,154 @@
+# mp-weixin-back
+
+> Vite plugin for intercepting back navigation (gesture back + navbar back button) in WeChat miniprogram (mp-weixin) built with uni-app + Vue 3.
+
+## When to use
+
+Use this library when you need to:
+- Intercept or customize the swipe-back gesture in a WeChat miniprogram page
+- Intercept or customize the navbar back button behavior
+- Show a confirmation dialog before the user leaves a page
+- Prevent accidental back navigation (e.g., on a form page)
+
+## Install
+
+```bash
+npm install mp-weixin-back
+# or
+pnpm add mp-weixin-back
+```
+
+## Setup (vite.config.ts)
+
+Register the Vite plugin once, globally:
+
+```ts
+import { defineConfig } from 'vite'
+import mpBackPlugin from 'mp-weixin-back'
+
+export default defineConfig({
+  plugins: [
+    mpBackPlugin({
+      preventDefault: false, // true = block all back navigation by default
+      frequency: 1,          // how many times to intercept before allowing through
+      debug: false,          // enable debug logging in development
+      onPageBack: ({ page }) => {
+        console.log('back triggered on page:', page)
+      },
+    }),
+  ],
+})
+```
+
+## Usage in Vue SFC (Composition API)
+
+Import from the virtual module `mp-weixin-back-helper`:
+
+```ts
+// Basic usage — listen to back event
+import onPageBack from 'mp-weixin-back-helper'
+
+onPageBack(() => {
+  console.log('back navigation detected')
+})
+```
+
+```ts
+// Advanced — prevent back and show dialog
+import onPageBack from 'mp-weixin-back-helper'
+
+onPageBack(
+  () => {
+    showConfirmDialog() // your logic here
+  },
+  {
+    preventDefault: true, // block default back behavior
+    frequency: 2,         // intercept 2 times
+    initialValue: true,   // start listening immediately (default)
+  }
+)
+```
+
+```ts
+// Manually toggle the listener
+import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
+
+onPageBack(() => { /* ... */ }, { initialValue: false }) // start disabled
+
+activeMpBack()   // enable listener (call inside <script setup>)
+inactiveMpBack() // disable listener (call inside <script setup>)
+```
+
+## TypeScript support
+
+Add to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["mp-weixin-back/client"]
+  }
+}
+```
+
+Or in `env.d.ts`:
+
+```ts
+/// <reference types="mp-weixin-back/client" />
+```
+
+## API Reference
+
+### Plugin options (`mpBackPlugin(options)`)
+
+| Option          | Type                              | Default | Description                                              |
+| --------------- | --------------------------------- | ------- | -------------------------------------------------------- |
+| `preventDefault`| `boolean`                         | `false` | Block default back behavior globally                     |
+| `frequency`     | `number`                          | `1`     | Number of times to intercept before allowing through     |
+| `debug`         | `boolean`                         | `false` | Log debug info in development mode                       |
+| `onPageBack`    | `(params: { page: string }) => void` | —    | Global callback fired on every back event                |
+
+### `onPageBack(callback, options?)`
+
+Listen to back events on the current page. Must be called in `<script setup>`.
+
+| Param      | Type                  | Required | Description                     |
+| ---------- | --------------------- | -------- | ------------------------------- |
+| `callback` | `() => void`          | Yes      | Function called when back fires |
+| `options`  | `OnPageBackOptions`   | No       | Per-page overrides              |
+
+#### `OnPageBackOptions`
+
+| Option          | Type      | Default | Description                                                  |
+| --------------- | --------- | ------- | ------------------------------------------------------------ |
+| `preventDefault`| `boolean` | `false` | Block default back for this page                             |
+| `frequency`     | `number`  | `1`     | Intercept count for this page                                |
+| `initialValue`  | `boolean` | `true`  | Start listening immediately; set `false` to enable manually  |
+
+### `activeMpBack()`
+
+Enable the back listener. Call inside `<script setup>` when `initialValue: false`.
+
+### `inactiveMpBack()`
+
+Disable the back listener. Call inside `<script setup>`.
+
+## How it works
+
+This is a **Vite transform plugin**. At build time it:
+1. Reads `src/pages.json` to identify miniprogram pages
+2. For each `.vue` page file, injects a `<page-container>` component into the template (the WeChat API used to intercept back gestures)
+3. Wires up the `onPageBack` composable to control `show` state of `<page-container>`
+
+The virtual module `mp-weixin-back-helper` is resolved by the plugin and provides the runtime composable API.
+
+## Constraints
+
+- Requires **uni-app** project with `src/pages.json`
+- Requires **Vue 3** + `<script setup>` (Composition API)
+- Works with **Vite 3–6**
+- Only applies to page-level `.vue` files, not components
+
+## Repository
+
+https://github.com/DBAAZzz/mp-weixin-back

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "mp-weixin-back",
   "type": "module",
-  "version": "0.0.15",
-  "description": "监听微信小程序的手势返回和页面默认导航栏的返回",
+  "version": "0.0.16",
+  "description": "Vite plugin to intercept back navigation (gesture back & navbar back) in WeChat miniprogram (mp-weixin) built with uni-app + Vue 3. 监听微信小程序的手势返回和页面默认导航栏的返回",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "scripts": {
-    "build": "unbuild",
-    "test": "vitest"
-  },
   "keywords": [
+    "miniprogram",
+    "wechat",
+    "mp-weixin",
+    "back-navigation",
+    "gesture-back",
+    "navigate-back",
+    "page-back",
+    "navigation-intercept",
+    "vite-plugin",
+    "uniapp",
+    "uni-app",
+    "vue3",
     "微信小程序",
     "手势返回",
-    "vite",
-    "uniapp"
+    "页面返回拦截"
   ],
   "exports": {
     ".": {
@@ -54,6 +61,7 @@
     "*": "prettier --write"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.29.8",
     "@types/babel__generator": "^7.6.8",
     "@types/node": "^22.9.3",
     "@vitejs/plugin-vue": "^5.2.0",
@@ -63,5 +71,12 @@
     "unbuild": "^2.0.0",
     "vitest": "^2.1.5",
     "vue": "^3.5.13"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
   }
-}
+}

package/readme.md

@@ -1,5 +1,30 @@
 # mp-weixin-back
 
+Vite plugin to intercept back navigation (gesture back + navbar back button) in WeChat miniprogram (mp-weixin) built with uni-app + Vue 3.
+
+## TL;DR
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import mpBackPlugin from 'mp-weixin-back'
+
+export default defineConfig({
+  plugins: [mpBackPlugin()],
+})
+```
+
+```ts
+// Any page .vue file — inside <script setup>
+import onPageBack from 'mp-weixin-back-helper'
+
+onPageBack(() => {
+  // handle back: show dialog, log analytics, etc.
+})
+```
+
+---
+
 ## 功能概述
 
 `mp-weixin-back` 是一个专门用于监听微信小程序`手势返回`、`导航栏返回事件`、`navigateBack`的工具库，提供灵活的配置选项和简洁的 API。
@@ -9,7 +34,7 @@
 ```bash
 npm install mp-weixin-back
 # 或
-yarn add mp-weixin-back
+pnpm add mp-weixin-back
 ```
 
 ## ⚙️ Vite 配置
@@ -27,9 +52,9 @@ export default defineConfig({
       preventDefault: false, // 是否阻止默认返回行为，设置成 true 则不会返回上一层
       frequency: 1, // 阻止次数，需要一直拦截则设置一个很大的值即可，如：9999
       debug: false, // 调试模式，默认为 false
-      onPageBack: () => {
-        console.log('返回事件触发')
-      }, // 统一钩子，事件触发时执行
+      onPageBack: ({ page }) => {
+        console.log('返回事件触发，当前页面：', page)
+      }, // 全局钩子，任意页面触发时执行
     }),
   ],
 })
@@ -68,24 +93,45 @@ onPageBack(
 )
 ```
 
+### 显示确认弹窗（常见场景）
+
+```ts
+<script setup>
+import onPageBack from 'mp-weixin-back-helper'
+
+onPageBack(
+  () => {
+    uni.showModal({
+      title: '提示',
+      content: '确定要离开当前页面吗？',
+      success: (res) => {
+        if (res.confirm) uni.navigateBack()
+      },
+    })
+  },
+  { preventDefault: true }
+)
+</script>
+```
+
 ## 📚 API 文档
 
-### `onPageBack(callback, config?)`
+### `onPageBack(callback, options?)`
 
-监听页面返回事件
+监听页面返回事件，必须在 `<script setup>` 顶层调用。
 
-| 参数     | 类型         | 必填 | 说明                     |
-| -------- | ------------ | ---- | ------------------------ |
-| callback | `() => void` | 是   | 返回事件触发时的回调函数 |
-| options  | Object       | 否   | 监听器配置选项           |
+| 参数       | 类型                | 必填 | 说明                     |
+| ---------- | ------------------- | ---- | ------------------------ |
+| `callback` | `() => void`        | 是   | 返回事件触发时的回调函数 |
+| `options`  | `OnPageBackOptions` | 否   | 监听器配置选项           |
 
-#### 配置选项
+#### 配置选项 `OnPageBackOptions`
 
-| 参数           | 类型    | 默认值 | 说明                                            |
-| -------------- | ------- | ------ | ----------------------------------------------- |
-| preventDefault | boolean | false  | 是否阻止默认返回行为（true 时页面不会实际返回） |
-| frequency      | number  | 1      | 阻止次数                                        |
-| initialValue   | boolean | true   | 是否立即启用监听（设为 false 时需手动激活）     |
+| 参数             | 类型      | 默认值  | 说明                                                            |
+| ---------------- | --------- | ------- | --------------------------------------------------------------- |
+| `preventDefault` | `boolean` | `false` | 是否阻止默认返回行为（`true` 时页面不会实际返回）               |
+| `frequency`      | `number`  | `1`     | 阻止次数                                                        |
+| `initialValue`   | `boolean` | `true`  | 是否立即启用监听（设为 `false` 时需手动调用 `activeMpBack()`）  |
 
 ### 辅助方法
 
@@ -103,20 +149,27 @@ onPageBack(
 <template>
   <div>
     <!-- 页面代码 -->
-    <button @click="toggleListener(true)">开启</button>
-    <button @click="toggleListener(false)">禁用</button>
+    <button @click="activeMpBack()">开启</button>
+    <button @click="inactiveMpBack()">禁用</button>
   </div>
 </template>
 
 <script setup>
   import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
 
-  const toggleListener = (enable) => {
-    enable ? activeMpBack() : inactiveMpBack()
-  }
+  onPageBack(() => { /* 处理返回 */ }, { initialValue: false })
 </script>
 ```
 
+### 插件全局配置 `mpBackPlugin(options)`
+
+| 参数             | 类型                                        | 默认值  | 说明                       |
+| ---------------- | ------------------------------------------- | ------- | -------------------------- |
+| `preventDefault` | `boolean`                                   | `false` | 全局阻止默认返回行为       |
+| `frequency`      | `number`                                    | `1`     | 全局阻止次数               |
+| `debug`          | `boolean`                                   | `false` | 开发模式下开启调试日志     |
+| `onPageBack`     | `(params: { page: string }) => void`        | —       | 全局回调，任意页面触发执行 |
+
 ## 🎯 选项式 API 支持（未完善）
 
 组件内直接声明
@@ -171,3 +224,10 @@ onPageBack(
 ### Q2: 全局配置与页面配置的优先级？
 
 页面级配置会覆盖全局配置，建议将通用配置放在全局，特殊需求在页面单独设置。
+
+### Q3: 不生效怎么排查？
+
+1. 确认 `src/pages.json` 存在且格式正确
+2. 确认是页面级 `.vue` 文件（非组件）
+3. 开启 `debug: true` 查看插件日志
+4. 确认 `@vue/compiler-sfc` 已安装：`pnpm add -D @vue/compiler-sfc`

package/src/context.ts

@@ -57,7 +57,11 @@ export class pageContext {
         }
       }
     } catch (error: unknown) {
-      this.log.error('读取pages.json文件失败')
+      this.log.error(
+        `Failed to read pages.json. Make sure src/pages.json exists and is valid JSON/JSON5.\n` +
+          `  Path checked: ${this.getPagesJsonPath()}\n` +
+          `  Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-配置`
+      )
       this.log.debugLog(String(error))
     }
   }

package/types/index.ts

@@ -1,35 +1,72 @@
-export type UserOptions = Partial<Config>
-
-export type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+export type BackParams = {
   /**
-   * 初始化时是否监听手势返回，默认值为`true`
+   * The path of the current page that triggered the back event.
+   * @example 'pages/index/index'
    */
-  initialValue: boolean
+  page: string
+}
+
+/**
+ * Per-page options for `onPageBack()`.
+ */
+export type OnPageBackOptions = {
   /**
-   * 是否阻止默认的回退事件，默认为 false
+   * Whether to block the default back navigation for this page.
+   * When `true`, the user stays on the current page and only the callback fires.
+   * @default false
+   * @example
+   * onPageBack(() => showDialog(), { preventDefault: true })
    */
   preventDefault: boolean
+
   /**
-   * 阻止次数，默认是 `1`
+   * How many times to intercept the back event before allowing through.
+   * Set to a large number (e.g. `9999`) for persistent interception.
+   * @default 1
+   * @example
+   * // Block 3 times, then allow back
+   * onPageBack(() => {}, { frequency: 3 })
    */
   frequency: number
+
   /**
-   * 调试模式
+   * Whether to start listening immediately when the page mounts.
+   * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+   * @default true
+   * @example
+   * // Start disabled, enable after user action
+   * onPageBack(() => {}, { initialValue: false })
+   * activeMpBack()
    */
-  debug: boolean
+  initialValue: boolean
+}
+
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+export type Config = OnPageBackOptions & {
   /**
-   * 页面回退时触发
+   * Enable debug logging in development mode.
+   * @default false
    */
-  onPageBack?: (params: BackParams) => void
-}
+  debug: boolean
 
-export type BackParams = {
   /**
-   * 当前页面路径
+   * Global callback fired every time a back event is detected on any page.
+   * Page-level callbacks registered via `onPageBack()` run in addition to this.
+   * @example
+   * mpBackPlugin({
+   *   onPageBack: ({ page }) => console.log('back on:', page)
+   * })
    */
-  page: string
+  onPageBack?: (params: BackParams) => void
 }
 
+export type UserOptions = Partial<Config>
+
 export type ContextConfig = Config & {
   mode: string
   root: string

package/utils/index.ts

@@ -23,9 +23,10 @@ async function resolveCompiler(root: string): Promise<typeof import('@vue/compil
         return await import('@vue/compiler-sfc')
       } catch (secondError) {
         throw new Error(
-          `无法解析 @vue/compiler-sfc。\n` +
-            `此插件需要项目中安装 @vue/compiler-sfc。\n` +
-            `请手动安装：pnpm add -D @vue/compiler-sfc\n`
+          `[mp-weixin-back] Cannot resolve @vue/compiler-sfc.\n` +
+            `This plugin requires @vue/compiler-sfc to be installed in your project.\n` +
+            `Fix: pnpm add -D @vue/compiler-sfc\n` +
+            `Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-配置\n`
         )
       }
     }
@@ -51,7 +52,10 @@ export async function transformVueFile(this: pageContext, code: string, id: stri
     const walker = scriptSetup ? 'compositionWalk' : 'optionsWalk'
     return vueWalker[walker](this, code, sfc, id)
   } catch (error) {
-    this.log.error('解析vue文件失败，请检查文件是否正确')
+    this.log.error(
+      `Failed to transform ${id}. Please check the file is a valid Vue SFC.\n` +
+        `  Docs: https://github.com/DBAAZzz/mp-weixin-back#-快速开始`
+    )
     this.log.error(String(error))
     return code
   }