@xiao-ying/miniapp-browser-bootstrap

用于在浏览器运行时同步注入 window.__XY_CONFIG__ 的 Vite 插件，并可按默认规则注入百度统计脚本。

为什么需要

@xiao-ying/miniapp-sdk-browser 会在模块初始化时读取 window.__XY_CONFIG__。 该插件在应用入口脚本执行前注入配置，确保浏览器环境下能用正确的 manifest 初始化 xy。

在以下场景会跳过注入：

• 检测到 App 运行时（宿主 WebView 已注入原生桥接）
• window.__XY_CONFIG__ 已存在

插件还内建了一套默认百度统计策略：

• 仅在 production mode 注入
• 仅在 https://miniapp.xiaoying.life 注入
• 默认百度统计站点 ID：ea8223f142dd84994c1ffe2e6123a028

这意味着业务小程序只要使用本插件并升级到包含该能力的版本，就不需要额外配置百度统计。

使用

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { miniAppBrowserBootstrapPlugin } from '@xiao-ying/miniapp-browser-bootstrap'

export default defineConfig({
  plugins: [
    react(),
    miniAppBrowserBootstrapPlugin({
      manifestByMode: {
        development: {
          id: 'miniapp-template',
          initialPath: '/',
          entryPrefix: '/#'
        },
        test: {
          id: 'miniapp-template',
          initialPath: '/',
          entryPrefix: '/#'
        },
        production: {
          id: 'miniapp-template',
          initialPath: '/',
          entryPrefix: '/#'
        }
      },
      themeSeedColor: '#4da3ff'
    })
  ]
})

主题色 seed 注入

浏览器运行时可通过插件同步注入宿主主题 seed color：

miniAppBrowserBootstrapPlugin({
  manifestByMode: {
    development: { id: 'miniapp-template', entryPrefix: '/#' },
    test: { id: 'miniapp-template', entryPrefix: '/#' },
    production: { id: 'miniapp-template', entryPrefix: '/#' }
  },
  themeSeedColor: '#4da3ff'
})

注入结果为：

window.__XY_CONFIG__ = {
  appearance: { themeSeedColor: '#4da3ff' }
}

如需按 Vite mode 覆盖，可使用 themeSeedColorByMode：

miniAppBrowserBootstrapPlugin({
  manifestByMode: {
    development: { id: 'miniapp-template', entryPrefix: '/#' },
    test: { id: 'miniapp-template', entryPrefix: '/#' },
    production: { id: 'miniapp-template', entryPrefix: '/#' }
  },
  themeSeedColor: '#4da3ff',
  themeSeedColorByMode: {
    development: '#2f5cf3'
  }
})

themeSeedColorByMode[mode] 优先级高于 themeSeedColor。颜色支持 #rgb 与 #rrggbb，插件会规范化为小写 #rrggbb 后注入。未配置时，@xiao-ying/miniapp-sdk-browser 会通过 SDK fallback 返回默认小应蓝 #4da3ff。

默认百度统计

不传任何额外配置时，插件会自动在以下条件下注入百度统计：

• 当前 Vite mode 为 production
• 页面运行在 https://miniapp.xiaoying.life

若只需要这套默认行为，无需给每个业务小程序单独增加配置。

禁用百度统计

若某个项目需要显式关闭默认百度统计，可传 false：

miniAppBrowserBootstrapPlugin({
  manifestByMode: {
    development: { id: 'miniapp-template', entryPrefix: '/#' },
    test: { id: 'miniapp-template', entryPrefix: '/#' },
    production: { id: 'miniapp-template', entryPrefix: '/#' }
  },
  baiduAnalytics: false
})

覆盖默认规则

若后续需要扩展到多个正式域名，或替换站点 ID，可显式覆盖规则：

miniAppBrowserBootstrapPlugin({
  manifestByMode: {
    development: { id: 'miniapp-template', entryPrefix: '/#' },
    test: { id: 'miniapp-template', entryPrefix: '/#' },
    production: { id: 'miniapp-template', entryPrefix: '/#' }
  },
  baiduAnalytics: {
    enabledModes: ['production'],
    rules: [
      {
        siteId: 'ea8223f142dd84994c1ffe2e6123a028',
        hosts: ['miniapp.xiaoying.life', 'miniapp2.xiaoying.life'],
        protocols: ['https']
      }
    ]
  }
})

开发二维码

默认会在 Vite dev server 启动后生成一张供 Flutter example 清单管理页扫码的 PNG：

miniAppBrowserBootstrapPlugin({
  manifestByMode: {
    development: { id: 'miniapp-template', entryPrefix: '/#' },
    test: { id: 'miniapp-template', entryPrefix: '/#' },
    production: { id: 'miniapp-template', entryPrefix: '/#' }
  }
})

默认只包含 Vite 的 Network URL，不包含 localhost / 127.0.0.1。如果终端提示没有可用 Network URL，请在项目 Vite 配置中设置：

export default defineConfig({
  server: {
    host: true
  }
})

二维码图片默认写入 node_modules/.vite/xy-miniapp/dev-server-qr.png，终端会打印绝对路径。按 Vite 的 h + enter 重新显示 server URLs 时，也会重新生成并打印二维码路径。

如果某个项目不需要开发二维码，可以显式传 devQrCode: false 关闭。

完整配置：

miniAppBrowserBootstrapPlugin({
  manifestByMode: {
    development: { id: 'miniapp-template', entryPrefix: '/#' },
    test: { id: 'miniapp-template', entryPrefix: '/#' },
    production: { id: 'miniapp-template', entryPrefix: '/#' }
  },
  devQrCode: {
    enabled: true,
    includeLoopback: false,
    outputDir: 'node_modules/.vite/xy-miniapp',
    fileName: 'dev-server-qr.png',
    idSeed: 'miniapp-template'
  }
})

二维码使用紧凑格式，类型为 xymd。当 manifest.id 不是 UUID 时，插件会基于 devQrCode.idSeed ?? manifest.id 生成稳定 UUID 作为 Flutter example 的本地清单记录 id，并把原始 manifest.id 写入清单 key，避免每次启动导入出一条新记录。

配置项

• manifestByMode（必填，以 Vite mode 为 key）
• manifestByMode.*.id（必填）
• manifestByMode.*.channel（可选，默认按 mode 推断：development -> dev，test -> beta，production -> prod）
• manifestByMode.*.initialPath（默认：/）
• manifestByMode.*.entryPrefix（必填）
• manifestByMode.*.name、manifestByMode.*.description、manifestByMode.*.iconUrl（可选）
• themeSeedColor（可选，浏览器运行时注入的宿主主题 seed color）
• themeSeedColorByMode（可选，以 Vite mode 为 key 覆盖 themeSeedColor）
• devQrCode（可选，默认开启；传 false 可关闭，传 true 或配置对象可自定义）
• devQrCode.enabled（可选，默认：true）
• devQrCode.includeLoopback（可选，默认：false）
• devQrCode.outputDir（可选，默认：node_modules/.vite/xy-miniapp）
• devQrCode.fileName（可选，默认：dev-server-qr.png）
• devQrCode.idSeed（可选，非 UUID manifest id 生成稳定记录 UUID 的种子）
• baiduAnalytics（可选，默认启用内建规则）
• baiduAnalytics.enabledModes（可选，默认：['production']）
• baiduAnalytics.rules（可选；若传入则覆盖默认规则）
• baiduAnalytics.rules.*.siteId（必填）
• baiduAnalytics.rules.*.hosts（必填，精确匹配 location.host，可包含端口）
• baiduAnalytics.rules.*.protocols（可选，默认：['https']）

entryPrefix 决定逻辑路径来源。若包含 #，使用 location.hash；否则使用 location.pathname + location.search。逻辑路径只在首次进入页面计算一次，不随路由变化更新。

manifest.host / manifest.protocol 总是从 window.location 自动推断。