可观测性开发工具前端后端【免费下载链接】openreplaySession replay, cobrowsing and product analytics you can self-host. Best for reproducing issues and iterating on your product.项目地址https://gitcode.com/gh_mirrors/op/openreplay点击查看免费下载sourcemap-uploader是 OpenReplay 官方提供的一个轻量级 NPM 模块用于把前端打包产物minified JS对应的 Source Map 文件上传到你的 OpenReplay 实例从而让会话回放与错误分析中的 JS 堆栈信息从压缩后的代码还原为可读的原始源码。本指南将基于 sourcemap-uploader 目录中的 README 与完整源码讲解安装、CLI 与 NPM API 两种用法、各参数含义以及从上传到后端存储、再到堆栈还原的完整链路帮助你在 CI/CD 或本地构建流程中直接落地使用。一、为什么需要上传 Source Map前端构建工具Webpack、Vite、Rollup 等默认会把源码压缩、混淆成体积更小的 JS 文件。当线上出现 JavaScript 异常时浏览器上报的错误堆栈指向的是压缩后的单行代码如app-42.js:1:2345几乎无法定位问题。OpenReplay 的错误分析Error Analysis功能依赖 Source Map 做反混淆通过 Source Map 将报错位置映射回原始源码文件、行号、列号与函数名还原出可读的调用栈。而这个还原的前提就是 Source Map 文件已经上传到 OpenReplay 的存储中。openreplay/sourcemap-uploader正是完成这一步的官方工具。在 OpenReplay 后端sourcemap 的读取与解析由 sourcemaps.py 与 sourcemaps_parser.py 承担前者负责签名上传/分享 URL 并组织 trace 帧后者将解析任务转发给独立的 sourcemap reader 服务由配置项sourcemaps_reader指定最终把压缩文件中的位置翻译成原始文件中的位置 上下文代码。二、安装该模块作为开发依赖安装到你的前端项目中即可它不会进入生产运行时代码npm i -D openreplay/sourcemap-uploader安装完成后模块会注册sourcemap-uploader命令行入口bin字段指向cli.js同时也暴露两个可直接在 Node.js 代码中调用的函数main字段指向index.js见 package.json。也就是说你可以选择在 npm scripts 中跑 CLI也可以在自定义的发布脚本中调用编程接口。三、CLI 用法CLI 有两种工作模式上传单个文件的 Source Mapfile子命令或递归上传一个目录下的所有 Source Mapdir子命令。1. 上传单个文件的 Source Mapsourcemap-uploader -s https://opnereplay.mycompany.com/api -k API_KEY -p PROJECT_KEY file -m ./dist/index.js.map -u https://myapp.com/index.js-m--sourcemap-file-path本地 Source Map 文件的路径-u--js-file-url这个 Source Map 对应的压缩 JS 文件在线上可访问的 URL即浏览器实际加载该 JS 时的地址。2. 上传目录下的所有 Source Mapsourcemap-uploader -s https://opnereplay.mycompany.com/api -k API_KEY -p PROJECT_KEY dir -m ./build -u https://myapp.com/static此时-u指定的是线上根 URL它必须与你从该目录上传 JS 文件时所对应的部署路径一致。例如./build目录下同时存在app-42.js和app-42.js.map而你希望它们被访问的地址是https://myapp.com/static/app-42.js那么-u就应填https://myapp.com/static。从 readDir.js 的实现可以确认 URL 的拼接规则使用glob递归匹配目录下所有**/*.map文件若-u末尾没有/会自动补上注释特别说明这里不能用简单字符串替换以免破坏 URL 的 schema每个.map文件对应的 JS URL 根 URL 该文件相对目录的相对路径并去掉.map后缀。因此./build/static/app-42.js.map会被映射为https://myapp.com/static/app-42.js。你只需要保证映射后的地址与线上实际加载 JS 的 URL 完全一致OpenReplay 才能把报错堆栈中的地址与已上传的 Source Map 对应起来。3. 全局参数说明参数长选项是否必填说明-k--api-key必填OpenReplay 的 API Key用于请求鉴权-p--project-key必填项目 KeyProject Key-i为已废弃的别名-s--server选填自建 OpenReplay 实例地址必须以/api结尾使用 OpenReplay SaaS 版时不要传此参数默认指向https://api.openreplay.com-l--logs选填输出请求日志verbose 模式-v--version选填打印模块版本号需要特别说明的是参数名与 README 描述存在一处细节差异以当前仓库源码为准在 cli.js 中-v实际绑定的是--version打印版本号而开启详细日志的开关是-l/--logs。源码中保留了一句注释Should be verbose, but conflicting on npm compilation into bin即作者本意将其作为 verbose 开关但为了避免与 npm 的 bin 编译冲突改用了-l。README 中提到的 verbose 能力对应到当前实现就是-l。CLI 成功执行后会输出类似Successfully uploaded N sourcemap file(s) for: ...的结果逐条列出成功上传的 JS 文件 URL如果目录下没有任何.map文件则提示No sourcemaps found in dir见 cli.js。四、NPM API 用法在自定义构建脚本中可以直接引用包内导出的两个异步函数见 index.jsuploadFile(api_key, project_key, sourcemap_file_path, js_file_url, [server]) uploadDir(api_key, project_key, sourcemap_dir_path, js_dir_url, [server])两个函数都返回 Promiseresolve 的值为成功上传了 Source Map 的文件列表即每个文件对应的 JS 文件 URL 数组。server为可选参数缺省时同样默认使用 OpenReplay SaaS 地址https://api.openreplay.com。示例上传单个文件const { uploadFile } require(openreplay/sourcemap-uploader); uploadFile( YOUR_API_KEY, YOUR_PROJECT_KEY, ./dist/index.js.map, https://myapp.com/index.js, https://openreplay.mycompany.com/api, // 自建实例SaaS 用户省略 ).then((files) { console.log(Uploaded sourcemaps for:, files); }).catch((e) { console.error(Failed:, e); });内部实现上uploadFile通过 readFile.js 以 UTF-8 读取本地.map文件内容并打包成{ sourcemap_file_path, js_file_url, body }结构uploadDir则先走上一节描述的递归匹配逻辑二者最终都汇入uploadSourcemaps完成上传。五、上传链路与后端原理了解底层协议有助于排查问题比如鉴权失败、地址不匹配等。整个上传过程是两步预签名presign流程由 uploadSourcemaps.js 实现第一步向 OpenReplay API 申请预签名上传 URL。CLI 发起一个PUT请求到{server}/{project_key}/sourcemaps/请求头携带Authorization: API_KEY请求体为{URL: [js_file_url, ...]}——这一步不会传输 Source Map 本身只是提交我要上传哪些 JS 文件对应的 Source Map。该请求对应的服务端实现位于 routers/core.pyPUT /{projectKey}/sourcemaps/端点接收请求体请求体由 schemas.py 中的SourcemapUploadPayloadSchema校验字段urls的别名正是URL。随后服务端调用 sourcemaps.py 中的presign_upload_urls为每个 URL 生成对象存储如 S3/MinIO的预签名上传地址expires_in1800即 30 分钟有效并返回给客户端。第二步把 Source Map 内容上传到预签名地址。客户端拿到返回的上传地址列表后对每个地址再发一次PUT请求携带Content-Length与Content-Type: application/json请求体即 Source Map 文件内容从而把文件写入配置的sourcemaps_bucket存储桶。上传完成后当 OpenReplay 收到 JS 异常堆栈时会走 sourcemaps.py 的get_traces_group流程为堆栈中的每个帧查找对应 Source Map先在存储桶中查找找不到再尝试远程.mapURL再由 sourcemaps_parser.py 把帧的位置信息line、column连同key、bucket等参数 POST 给 sourcemap reader 服务拿回还原后的原始堆栈与上下文代码。常见的服务端响应与处理403鉴权被拒绝工具会提示Authorisation rejected. Please, check your API_KEY and/or PROJECT_KEY.——请核对 API Key 与 Project Key 是否正确、是否对该项目有权限其他非200状态码服务端错误提示联系 OpenReplay 支持预签名 URL 上传失败同样以服务端错误提示并可在开启 verbose-l后看到具体的响应状态码与响应体便于定位。六、本地开发与调试如果你在本地调试该模块本身仓库提供了开发脚本 run-dev.shnpm install bash run-dev.sh该脚本读取本地.env文件中的API_KEY、PROJECT_KEY、USERVER、TARGET_URL变量然后以 verbose 模式执行一次目录上传默认目录为./maps。它等价于手动执行node cli.js -l -k $API_KEY -p $PROJECT_KEY -s $USERVER dir -m ./maps -u $TARGET_URL将调试用的.map文件放入./maps目录后运行即可观察完整的请求/响应日志验证自己的上传链路是否打通。七、使用建议与注意事项自建实例务必加/api后缀-s参数期望的是 OpenReplay API 服务地址例如https://openreplay.mycompany.com/api这与后端路由/{projectKey}/sourcemaps/的挂载位置相对应SaaS 用户不要传-s源码中默认值会落到https://api.openreplay.com。JS URL 必须与线上真实地址一致无论是file还是dir模式-u构造出的地址必须与浏览器实际加载压缩 JS 的 URL 完全匹配包括路径与目录层级否则堆栈还原时无法命中对应的 Source Map。建议在构建后立即上传把上传命令挂到 CI/CD 的构建产物发布阶段保证部署新版本的同时 Source Map 已就位预签名地址有效期 30 分钟上传动作应紧跟构建完成之后执行避免过期。Source Map 不上传到公网Source Map 内容只会写入你配置的对象存储sourcemaps_bucket不需要也不建议把.map文件暴露到生产静态站点这既保护了源码隐私也让错误还原链路更可控。目录模式目前不支持排除源码中留有// TODO: exclude in dir注释cli.js即当前版本dir会递归上传目录内所有*.map文件如目录中存在不需要上传的 Source Map请规划好构建输出目录结构。关于存储与解析相关配置如sourcemaps_bucket、sourcemaps_reader、SMR_KEY、sourcemapTimeout等可以在 api/env.default 与 api/env.dev 中查看默认值并按自建部署的存储环境进行调整。赞分享可观测性开发工具前端后端【免费下载链接】openreplaySession replay, cobrowsing and product analytics you can self-host. Best for reproducing issues and iterating on your product.项目地址https://gitcode.com/gh_mirrors/op/openreplay点击查看免费下载相关推荐OpenReplay SourceMap 上传教程让压缩后的 JS 错误堆栈瞬间可读的简单方法OpenReplay SourceMap 上传教程让压缩后的 JS 错误堆栈瞬间可读的简单方法 生产环境的 JS 经过压缩混淆后OpenReplay 捕获到可观测性开发工具前端后端OpenReplay 自托管 PostgreSQL 18 Docker 镜像构建与 Kubernetes 部署指南OpenReplay 自托管 PostgreSQL 18 Docker 镜像构建与 Kubernetes 部署指南 OpenReplay 仓库在 scripts可观测性开发工具前端后端OpenReplay 网络代理库openreplay/network-proxy完全指南拦截 fetch、XHR 与 Beacon 实现网络请求追踪OpenReplay 网络代理库openreplay/network proxy完全指南拦截 fetch、XHR 与 Beacon 实现网络请求追踪 O可观测性开发工具前端后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
