配置项参考

组件的所有行为都由一个全局对象 window.BugCapturerConfig 控制，它必须在 SDK 脚本之前定义（SDK 在执行时读取它）。本页列出全部字段及其类型、默认值与行为。

<script>
  window.BugCapturerConfig = {
    key: "bcpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 必填
    // 以下全部可选
  };
</script>
<script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>

字段

字段	类型	默认值	说明
key	string	—（必填）	项目公开 SDK key（bcpk_ 前缀）。只用于标识项目；真正的鉴权靠项目的域名白名单，不靠 key 保密
api	string	https://api.bugcapturer.com	API 域名。仅自部署 / 反代场景需要覆盖；结尾不要带斜杠
position	string	bottom-right	悬浮球初始位置：bottom-right / bottom-left / top-right / top-left。访客拖动过之后，位置按站点记忆（localStorage），并优先于此值
requireContact	boolean	false	匿名访客提交前必须留联系方式。服务端的项目配置会做同样的校验——两处请保持一致
reporter	object	{ uid: "", name: "", email: "" }	挂在每条报告上的身份。匿名站点留空；有登录的站点按当前用户填写（服务端渲染）或调用 identify()——绝不写死某个人的身份
lang	string	跟随浏览器语言	组件 UI 语言：zh 或 en。不为 zh 开头的值一律按 en 处理
tipDelay	number	5	访客在页面停留多少秒后弹出提示气泡；0 表示加载后立即弹出
tipDuration	number	5	提示气泡的显示时长（秒）
tipOnce	boolean	true	每个访客只弹一次（localStorage 记忆）；设为 false 则每次进入页面都弹
exposeReporter	boolean	true	是否允许 BugCapturer.getReporter()（以及 BugCapturer 插件）读取本页传入的反馈人身份。更严格的隐私策略可设为 false；不影响报告提交，只是关闭本地读取接口

注意与坑

key 是公开的，这是设计使然

SDK key 本来就在页面源码里。任何人都可以在你放行的域名上加载组件；但没人能在你未允许的域名上提交，而且所有人都会被限流。轮换 key 的方式是删除并重建项目。

requireContact 是个双向开关

嵌入配置决定表单问不问；项目里的 Widget 设置会在服务端同样生效。如果项目开了必填、而报告提交时没有联系方式，服务端会拒绝——所以切换时两处一起改（或只在项目设置里改，再把代码里的值同步一下）。

reporter 与 identify() 的关系

两者设置的是同一个身份，后写者生效。经验法则：

• 服务端渲染页面 → 在模板里按用户填充 reporter
• SPA / 前端态会话 → 登录后调用 identify()
• 无登录 → 留空（匿名）

时序

SDK 只在脚本执行时读取一次配置。把配置写在 SDK 标签之后（或之后才条件性地赋值），是「悬浮球永远不出现」的最常见原因。上面示例里的标签顺序是必须的。

最小配置示例

匿名营销站：

<script>
  window.BugCapturerConfig = { key: "bcpk_…" };
</script>

登录态 UAT 环境（服务端渲染、联系方式非必填）：

<script>
  window.BugCapturerConfig = {
    key: "bcpk_…",
    position: "bottom-left",
    reporter: { uid: "${user.id}", name: "${user.name}", email: "${user.email}" }
  };
</script>

延伸阅读

• 反馈人身份 —— 怎样正确填 reporter