可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载导读本文基于 sentry-javascript 仓库的维护技能文档.agents/skills/bump-size-limit/SKILL.md系统讲解当 size-limit GitHub Action 检查失败时如何正确完成全量构建 → JSON 模式测量 → 定位失败场景 → 计算新阈值 → 更新.size-limit.js→ 复验的完整流程。读完本文你将掌握 size-limit 输出的 JSON 字段含义、KB 与 KiB 两种单位的换算规则以及仓库内手动调阈值与每周自动 bump 两条并行的维护路径。背景sentry-javascript 如何用 size-limit 守护包体积sentry-javascript 是一个包含 Browser、Node、React、Vue、Svelte、Next.js、Cloudflare 等数十个 SDK 包的 monorepo。为了守住引入 SDK 后用户包体积增长可控这条红线仓库在根目录维护了一个 .size-limit.js 配置文件由 size-limit 工具在 CI 中执行测量。触发检查的脚本定义在根目录 package.jsontest:size-limit: yarn size-limit --json,当 CI 中的 size-limit 检查失败时本质含义是某个或多个 bundle 场景的实际体积size超过了.size-limit.js中为该场景配置的字节阈值sizeLimit。这通常发生在新增功能、引入新依赖或重构后产物体积自然增长时。本文的 Skill 文档给出了处理该问题的标准操作流程。完整手动工作流六步完成阈值调整Skill 文档规定了严格的操作顺序核心原则是只调整真正失败的场景绝不触碰通过的场景。以下六个步骤完整继承自该文档并补充了仓库内的实现佐证。Step 1全量构建含 CDN bundlesyarn buildsize-limit 测量的是实际编译后的产物因此必须先完成全量构建。该命令在 package.json 中被定义为build: node ./scripts/verify-packages-versions.js nx run-many -t build:transpile build:types build:bundle,注意构建需要几分钟时间且必须保证packages/browser/build/bundles/下的 CDN bundle 是最新的——dev build如yarn build:dev不足以支撑 size-limit 测量因为 CDN 场景直接指向这些 bundle 文件。Step 2以 JSON 模式运行体积检查yarn test:size-limit对应 package.json 中的yarn size-limit --json。--json标志让 size-limit 输出结构化 JSON 而非人类可读文本便于脚本解析和筛选。Step 3从 JSON 输出中识别失败场景JSON 输出是一个对象数组每个对象包含四个核心字段Skill 文档原文定义字段含义name场景标签如sentry/browser、CDN Bundle (incl. Tracing)passed布尔值是否在配置的阈值内size实际体积字节sizeLimit配置的体积上限字节用过滤器筛选出passed: false的条目——这些是唯一需要调整阈值的场景。Step 4计算新阈值保守向上取整启发式对于每个失败场景将实际体积向上取整到下一个完整 KB。Skill 文档特别强调在本仓库的语境下1 KB 1000 字节十进制这与 size-limit 解析.size-limit.js中130 KB这类字符串的方式一致。文档示例实际体积为129,127字节时新阈值为130 KB即 130,000 字节。这个启发式刻意保持保守——只给出恰好足够的余量避免无谓地虚高所有场景的阈值。向下取整或保留小数是不允许的因为它无法保证给出完整余量。Step 5更新.size-limit.js打开仓库根目录的 .size-limit.js定位到每个失败场景的limit字段并更新。limit是字符串格式形如130 KB{ name: sentry/browser, path: packages/browser/build/npm/esm/prod/index.js, import: createImport(init), gzip: true, limit: 34 KB, // ← 修改这里 disablePlugins: [size-limit/esbuild], },只修改实际失败的场景。通过的场景保持原样避免人为扩大整个仓库的体积基线。Step 6复验修复yarn test:size-limit重新运行检查确认全部通过。如果仍有场景失败例如取整边界问题只针对该具体场景再增加 1 KB然后再次运行。反复执行直到绿灯。深入解析.size-limit.js结构、字段与单位对 .size-limit.js共 531 行的源码分析可以确认该文件由一组场景对象组成每个对象除了name、path、limit外还大量使用以下字段import指定测量时从入口导入的符号文件底部 createImport 辅助函数将参数拼接为{ init, browserTracingIntegration }形式的解构导入gzip/brotli是否启用 gzip/brotli 压缩测量。CDN 压缩场景默认gzip: true而非压缩场景显式声明gzip: false, brotli: false见 非压缩 CDN 场景ignore从 bundle 中排除的模块如 Node SDK 场景忽略builtinModules与node:前缀的内置模块.size-limit.jsReact 场景忽略react/jsx-runtimedisablePlugins禁用size-limit/esbuild或size-limit/webpack例如 Cloudflare 场景因使用 esbuild 测量而禁用 webpack 插件.size-limit.jsmodifyWebpackConfig/modifyEsbuildConfig函数形式的自定义构建配置用于模拟真实使用场景。例如 browser treeshaking 场景 通过webpack.DefinePlugin关闭调试标志和 Replay Workersentry/node/import场景则强制保留副作用以真实测量 Node 运行时加载量.size-limit.jswebpack: false对 Cloudflare 场景直接关闭 webpack 链路改用modifyEsbuildConfig对齐wrangler deploy的构建参数.size-limit.js。单位问题需要特别留意该文件绝大多数场景使用十进制KB1 KB 1000 字节但 Cloudflare 的两个场景使用的是二进制KiB.size-limit.js 中的limit: 205 KiB这是为了匹配wrangler deploy的输出口径。手动调整时必须确认目标场景的单位不要跨单位照搬数值。场景覆盖范围从文件结构看可归纳为几大类Browser SDK 各功能组合Tracing / Replay / Feedback / Metrics / Logs 的排列组合、React/Vue/Svelte SDK、Browser CDN bundles压缩与非压缩两套、Next.js 与 SvelteKit 客户端入口、sentry/core子路径入口、Node SDK 多个变体、AWS Serverless、Cloudflare Worker SDK。仓库内的自动化补充自动 bump 脚本除了 Skill 文档描述的手动流程仓库还提供了自动化脚本 scripts/bump-size-limits.mjs可以作为理解阈值计算规则的对照实现。该脚本的启发式与手动流程略有不同它计算ceil((实际体积 5000) / 1000) * 1000即先加 5 KB 安全余量再向上取整到整 KB见 computeNewLimit常量定义于 第 24-26 行HEADROOM_BYTES 5000、BYTES_PER_KB 1000、BYTES_PER_KIB 1024。该脚本有几个值得借鉴的实现细节通过yarn --silent size-limit --json以无 shell 方式执行并捕获 stdoutmain 入口即使 size-limit 因超限返回非零退出码也保留 JSON 输出继续解析绝不require().size-limit.js而是以纯文本方式读取并用正则按name:精确匹配后重写limit:行rewriteSizeLimitFile因为该文件内含用户自定义的 webpack/esbuild 配置函数不应被脚本执行通过临时文件 rename 实现原子写入第 236-240 行单位换算后显示值未变化时跳过编辑避免 KiB 取整造成的无效变更第 213-217 行。该脚本由每周自动 workflow .github/workflows/bump-size-limits.yml 驱动提交信息为chore(size-limit): auto-bump weekly drift以bot/bump-size-limits分支发起 PR。手动 bump 与自动 bump 是两条互补路径手动流程适合 PR 开发过程中的即时修复自动脚本负责每周消除累积的体积漂移。CI 中的 size-limit 检查链路了解检查如何接入 CI有助于理解为何失败以及为何必须这样修。仓库的 size-limit 检查集成在 .github/workflows/build.yml 的 Check bundle sizes 步骤中- name: Check bundle sizes uses: ./dev-packages/size-limit-gh-action with: github_token: ${{ secrets.GITHUB_TOKEN }} # Only run comparison against develop if this is a PR comparison_branch: ${{ (github.event_name pull_request github.base_ref) || }}该 action 的实现位于 dev-packages/size-limit-gh-action/index.mjs核心行为包括执行yarn run --silent size-limit --json获取当前分支测量结果execSizeLimit通过 SizeLimitFormatter.parseResults 将 JSON 解析为{ name, size, sizeLimit, passed }结构——这正是 Skill 文档 Step 3 所依赖的字段来源若配置了comparison_branchPR 场景下为 develop则拉取对比分支的测量 artifact按 hasSizeChanges 计算相对阈值内是否存在变化决定是否在 PR 上发布/更新 Markdown 对比表格若 size-limit 进程返回非零状态则以setFailed(Size limit has been exceeded.)标记检查失败index.mjs 第 183-203 行并在日志中输出超限场景列表Exceeded size-limits:。Action 的输入参数定义在 dev-packages/size-limit-gh-action/action.ymlgithub_token必填、comparison_branch可选指定对比分支、threshold默认0.0125即体积相对变化超过 1.25% 才发布评论。这套链路回答了 Skill 文档的隐含问题当 CI 报错时报错信息中的Exceeded size-limits列表对应的就是.size-limit.js中需要 bump 的场景与手动流程 Step 3 的筛选结果一致。边界情况与最佳实践综合 Skill 文档与仓库实现实践中有几点值得注意取整边界129,900字节这类恰好接近整 KB 上限的数值按向上取整规则会得到130 KB仅给出 100 字节余量。复验时若仍失败如测量存在微小波动按 Skill 文档规定对该场景单独 1 KB 后重跑不要批量上调其他场景。KB 与 KiB 混用绝大多数场景用十进制KB1000 进制Cloudflare 场景用KiB1024 进制。手动计算时以场景现有单位为准自动脚本 bytesToDisplay 正是按cur.unit动态选择除数。改后必须复验.size-limit.js中的modifyWebpackConfig/modifyEsbuildConfig会影响测量结果修改limit后重新运行yarn test:size-limit是唯一可靠的验证方式。保持最小改动只 bump 失败场景避免通过阈值膨胀掩盖未来的体积回归这既是 Skill 文档的硬性规定也符合自动脚本显示值未变化则跳过的克制策略。小结当 sentry-javascript 的 size-limit CI 检查失败时标准处理流程可浓缩为yarn build全量构建 →yarn test:size-limit以 JSON 模式测量 → 筛选passed: false的场景 → 按 1 KB 1000 字节向上取整计算新阈值 → 只更新.size-limit.js中失败场景的limit→ 重跑复验必要时单场景 1 KB 迭代。若希望了解仓库如何自动化这一过程可进一步阅读 scripts/bump-size-limits.mjs手动流程的脚本化对照与 dev-packages/size-limit-gh-actionCI 检查的实现源头。赞分享可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载相关推荐Effect 仓库 Bundle Size 开发工作流实战用 Rollup gzip 测量、对比与分析包体积Effect 仓库 Bundle Size 开发工作流实战用 Rollup gzip 测量、对比与分析包体积 本文面向在 .repos/effect smAI Agent代码智能体后端前端移动开发桌面应用tmux-rs快速入门如何在5分钟内安装和运行Rust版tmux tmux rs快速入门如何在5分钟内安装和运行Rust版tmux 想要体验用Rust语言重新实现的tmux终端复用器吗tmux rs是一个激动人心的开Size Limit 性能基准测试如何建立科学的评估体系Size Limit 性能基准测试如何建立科学的评估体系 在现代前端开发中JavaScript 应用和库的体积控制已成为保证用户体验的关键因素。 Size开发工具前端测试上一篇终极指南掌握DesignPatternsPHP中的Behavioral模式核心原理与实战应用下一篇C Insights折叠表达式参数包展开的编译器处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
