config-synch

一个面向浏览器的配置同步 npm 包，适合通过 iframe 把 JSON 配置下发到多个业务站点，并在目标站点通过 localStorage 变化触发自己的业务回调。

包内提供两类能力：

1. 配置下发：业务页面动态加载目标站点的桥接页 iframe，下发 JSON 配置，收到确认后自动销毁
2. 配置监听：监听指定 localStorage key 的变化，并把解析后的配置交给业务回调处理

另外还内置一个静态桥接页：

• dist/sync-bridge.html

这个页面会在 iframe 中接收父页面发来的 JSON 配置，写入目标站点自己的 localStorage。

安装

npm install @your-scope/config-synch

构建

npm install
npm run build

构建产物：

• dist/index.mjs：ESM
• dist/index.cjs：CommonJS
• dist/index.d.ts：类型声明
• dist/sync-bridge.html：桥接页

使用方式

1. 在业务站点部署桥接页

把 node_modules/@your-scope/config-synch/dist/sync-bridge.html 发布到业务站点的静态资源目录，例如：

• https://site-a.example.com/sync-bridge.html
• https://site-b.example.com/sync-bridge.html

2. 在配置下发端调用同步方法

import { syncConfigToSites } from "@your-scope/config-synch";

await syncConfigToSites({
  storageKey: "demo:site-config",
  payload: {
    featureFlags: {
      useNewHeader: true,
      enableUpload: false
    },
    theme: {
      primaryColor: "#1677ff"
    }
  },
  targets: [
    {
      name: "site-a",
      iframeUrl: "https://site-a.example.com/sync-bridge.html"
    },
    {
      name: "site-b",
      iframeUrl: "https://site-b.example.com/sync-bridge.html"
    }
  ]
});

如果只同步一个站点：

import { syncConfigToSite } from "@your-scope/config-synch";

await syncConfigToSite({
  iframeUrl: "https://site-a.example.com/sync-bridge.html",
  storageKey: "demo:site-config",
  payload: {
    env: "prod",
    allowRegister: true
  }
});

3. 在目标业务站点监听配置变化

import { watchStorageConfig } from "@your-scope/config-synch";

const stop = watchStorageConfig({
  storageKey: "demo:site-config",
  immediate: true,
  onChange(config) {
    console.log("配置已更新", config);
    // 在这里执行业务自己的刷新逻辑
  }
});

// 页面销毁时取消监听
stop();

API

syncConfigToSite(options)

向单个业务站点同步配置。

关键参数：

• iframeUrl: string：目标站点桥接页地址
• storageKey: string：目标站点写入 localStorage 的 key
• payload: JsonValue：任意合法 JSON 配置
• targetOrigin?: string：默认从 iframeUrl 自动解析
• timeoutMs?: number：默认 10000
• destroyOnComplete?: boolean：默认 true

syncConfigToSites(options)

批量向多个业务站点同步配置。支持在 targets 内按站点覆盖 storageKey、payload、timeoutMs。

createConfigSyncSession(options)

创建一个可复用的同步会话，返回：

• run()：执行一次同步
• destroy()：主动销毁 iframe
• getIframe()：读取当前 iframe 实例

适合你需要手动控制“触发同步”和“完成后销毁”的场景。

watchStorageConfig(options)

监听指定 localStorage key 的变化。

关键参数：

• storageKey: string
• onChange(payload, meta)：配置变化后的回调
• immediate?: boolean：是否立即读一次当前值
• pollIntervalMs?: number：可选轮询兜底，处理某些不触发 storage 事件的场景
• parse?: (rawValue) => T：自定义解析函数

readStoredConfig(storageKey, parse?, storage?)

主动读取并解析指定 key 的本地配置。

桥接页消息协议

父页面发送：

{
  "channel": "config-synch",
  "type": "config-synch:set",
  "requestId": "uuid",
  "storageKey": "demo:site-config",
  "payload": {
    "featureFlags": {
      "useNewHeader": true
    }
  },
  "sentAt": "2026-07-05T12:00:00.000Z"
}

桥接页返回：

{
  "channel": "config-synch",
  "type": "config-synch:ack",
  "requestId": "uuid",
  "ok": true,
  "storageKey": "demo:site-config",
  "writtenAt": "2026-07-05T12:00:01.000Z"
}

npm 发布前需要填写的字段

发布前请把下面这些字段补完整：

• package.json > name
• package.json > author
• package.json > repository.url
• package.json > homepage
• package.json > bugs.url

npm 发布步骤

npm login
npm run build
npm publish --access public

如果你用的是组织 scope，先确认组织允许 public package。

设计约束

• 配置内容必须是合法 JSON
• 目标站点桥接页必须和目标业务页面同源，这样写入的 localStorage 才能被业务代码直接读取
• 包本身只负责同步和监听，不约束业务配置结构