5 分钟快速接入
本指南使用 Script 标签完成最短接入。它不依赖具体前端框架，适用于普通 HTML、Vue、Nuxt、React 以及使用 History API 的单页应用。
准备工作
开始前，你需要：
- 一个可以访问的 Web 应用域名
- TraceVista 控制台账号
- 修改页面 HTML 或应用模板的权限
1. 添加监控网站
登录控制台，选择“添加网站”，填写：
- 网站名称：便于团队识别，例如“商城生产环境”
- 网站域名：只填写域名，例如
shop.example.com，不要包含协议、端口或路径
网站域名必须与用户实际打开页面时的 hostname 完全一致。协议和端口不参与比较，但 example.com、www.example.com 和 shop.example.com 会被视为三个不同域名。SDK 从其他域名、本地 localhost 或预览地址上报时会返回 403。
添加完成后，进入网站设置并复制 API Key。Key 的形式类似：
mk_your_project_key
2. 安装 SDK
把控制台提供的代码放在页面的 <head> 中：
<script
defer
src="https://apm.noxussj.top/monitor.min.js"
data-project-key="mk_your_project_key">
</script>
请将示例中的 API Key 替换为控制台显示的 Key。defer 会让脚本在 HTML 解析完成后执行，避免阻塞页面解析。
Nuxt 项目示例
可以在 nuxt.config.ts 中声明全局脚本：
export default defineNuxtConfig({
app: {
head: {
script: [
{
src: 'https://apm.noxussj.top/monitor.min.js',
defer: true,
'data-project-key': 'mk_your_project_key'
}
]
}
}
})
建议通过 Nuxt 运行时配置或部署变量管理不同环境的 API Key。
3. 产生验证数据
部署或启动网站后：
- 打开一个安装了 SDK 的页面。
- 在页面间跳转一次。
- 打开浏览器开发者工具，确认 SDK 文件成功加载。
- 回到 TraceVista 控制台刷新网站数据。
访问数据通常会先出现；性能数据会在页面隐藏、卸载或 SDK 启动约 10 秒后提交。
4. 记录第一个业务事件
SDK 加载后，可以通过全局对象记录关键行为：
const accepted = await window.TraceVista.track('signup_completed', {
plan: 'free',
source: 'homepage'
})
返回值为 Promise<boolean>：true 表示本次上报被接口接受，false 表示未启动、被限流、额度已用完或请求失败。
接入检查清单
- 生产环境使用生产网站的 API Key
- 网站设置中的绑定域名与页面
Origin的 hostname 完全一致 - SDK 地址可以通过 HTTPS 正常访问
- 页面没有重复安装 SDK
- CSP 允许加载 SDK 并向监控接口发起请求
- 测试事件中没有密码、Token、手机号等敏感数据
- 控制台能看到访问、性能或错误数据
没有看到数据？
临时开启调试日志：
<script
defer
src="https://apm.noxussj.top/monitor.min.js"
data-project-key="mk_your_project_key"
data-debug="true">
</script>
然后检查控制台是否提示 Key 缺失、上报失败或额度耗尽。更多配置请阅读 SDK 配置。
如果上报接口返回 403，请打开 Network 面板中该请求的 Response：APIKEY 与当前网站域名不匹配 表示绑定域名与请求 Origin（缺失时使用 Referer）不一致。重点检查 www、子域名、本地地址和是否误用了其他网站的 API Key。完整排查方法见 API Key 与绑定域名。