@zayn919/minisentry-sourcemap

给第三方业务项目用的 SourceMap 上传工具：接入一次后，npm run build 自动把全部 .map 推到 Mini Sentry。

安装

npm install -D @zayn919/minisentry-sourcemap

方式一：Vite 插件（推荐）

// vite.config.ts
import { defineConfig } from 'vite'
import { minisentrySourcemap } from '@zayn919/minisentry-sourcemap/vite'

export default defineConfig({
  build: { sourcemap: true }, // 必须生成 map
  plugins: [
    minisentrySourcemap({
      // 下面也可全部用环境变量，不必写死在仓库里
      url: process.env.MINISENTRY_URL,
      project: process.env.MINISENTRY_PROJECT,
      release: process.env.MINISENTRY_RELEASE || process.env.npm_package_version,
    }),
  ],
})

业务项目 package.json 不用改脚本：

{
  "scripts": {
    "build": "vite build"
  }
}

CI / 本机注入密钥（勿提交到 Git）：

export MINISENTRY_URL=https://sentry.example.com
export MINISENTRY_PROJECT=1
export [email protected]   # 须与 SDK init({ release }) 一致
export MINISENTRY_AUTH_TOKEN=ms_sm_... # Dashboard 应用设置中生成的项目级 CI Token
# 或用账号（每次构建自动登录换 token）：
# export MINISENTRY_USER=ci-bot
# export MINISENTRY_PASSWORD=***

npm run build

未配置 token/账号时插件自动跳过，本地 vite build 不受影响。

方式二：CLI（Webpack / Rollup / 任意构建）

{
  "scripts": {
    "build": "webpack --mode production && minisentry-sourcemaps upload --dir dist"
  }
}

minisentry-sourcemaps upload \
  --url https://sentry.example.com \
  --project 1 \
  --release [email protected] \
  --dir dist \
  --token "$MINISENTRY_AUTH_TOKEN"

接入自检与发布门禁

minisentry-sourcemaps doctor --url https://sentry.example.com --dsn "$MINISENTRY_DSN" --project 1 --token "$MINISENTRY_AUTH_TOKEN" --fail-on-error

minisentry-sourcemaps quality-check --url https://sentry.example.com --project 1 --token "$MINISENTRY_AUTH_TOKEN" --base 10 --target 11 --environment production --window 30

quality-check 默认只报告：

• 未配置项目质量规则：结果恒为 warn（超阈也不 fail），避免默认阈值误阻断流水线
• 已配置规则：超阈为 fail，通过为 pass
• 只有增加 --fail-on-fail 才在结果为 fail 时返回非零退出码

两条命令均支持 --json。

方式三：代码调用

import { uploadSourceMaps } from '@zayn919/minisentry-sourcemap'

await uploadSourceMaps({
  url: 'https://sentry.example.com',
  project: 1,
  release: '[email protected]',
  dir: 'dist',
  token: process.env.MINISENTRY_AUTH_TOKEN,
})

环境变量

| 变量 | 说明 | |------|------| | MINISENTRY_URL | API 根地址 | | MINISENTRY_PROJECT | 数字项目 ID | | MINISENTRY_RELEASE | 版本号（与 SDK release 一致） | | MINISENTRY_AUTH_TOKEN | 项目级 SourceMap CI Token（推荐）或管理员 JWT | | MINISENTRY_USER / MINISENTRY_PASSWORD | 无 token 时自动登录 | | MINISENTRY_DRY_RUN=1 | 只列出不上传 | | MINISENTRY_FAIL_ON_ERROR=1 | 失败则让构建失败 | | MINISENTRY_SILENT=1 | 少日志 | | MINISENTRY_BATCH_SIZE | 每批最多文件数（默认 40，服务端上限 200） | | MINISENTRY_BATCH_MAX_BYTES | 每批最大体积（默认 8388608=8MB） |

注意

1. SDK init({ release }) 必须与上传的 release 一致。
2. 构建需开启 sourcemap（Vite：build.sourcemap: true；Vue CLI：productionSourceMap: true）。
3. CLI 需要 Node.js >= 16（18+ 用内置 fetch，16 自动回退 undici）；文件很多时会自动分批（默认每批 ≤40 个 / ≤8MB），避免网关 413。
4. 若仍报 413 Request Entity Too Large，在 OpenResty/Nginx 增加：client_max_body_size 50m;（对本仓库 deploy/nginx.conf 的 /api/ 已默认 50m）。
5. CI 推荐使用项目级 CI Token；可上传 SourceMap，并调用 Release 状态 / 基线 / quality-check；跨项目无效，可在 Dashboard 随时轮换或撤销。
6. 默认上传失败不打断构建；要严格校验请设 failOnError: true 或 MINISENTRY_FAIL_ON_ERROR=1。
7. quality-check：无项目规则时只 warn；已配置规则后的 fail 需加 --fail-on-fail 才会阻断 CI。
8. 业务线上不要公开 .map：map 只上传到 Mini Sentry；部署静态资源时排除，例如：

npm run build
# 插件/CLI 已上传 map 后：
rsync -avz --delete \
  --exclude '*.map' \
  --exclude '**/*.map' \
  ./dist/ \
  user@server:/var/www/app/