webfunny-webpack-plugin

v1.0.1

Published

6 months ago

Webpack plugin and CLI tool for uploading source maps to Webfunny monitoring system

0High
0Medium
0Low

a826604005

sourcemap upload cli webfunny

Webfunny Webpack Plugin

一个用于将 Source Map 文件上传到 Webfunny 监控系统的 Webpack 插件 和 CLI 工具。

功能特点

🔌 Webpack 插件：构建完成后自动上传 SourceMap
🚀 CLI 工具：快速批量上传 Source Map 文件
📦 自动扫描指定目录下的所有 .map 文件
🗑️ 上传后自动删除 .map 文件（可配置）
✅ 上传进度实时反馈
🎯 类似 Sentry 的使用体验

安装

全局安装

npm install -g webfunny-webpack-plugin

项目内安装

npm install --save-dev webfunny-webpack-plugin

使用方法

方式一：Webpack 插件（推荐）

在 webpack.config.js 中配置：

const WebfunnyWebpackPlugin = require('webfunny-webpack-plugin');

module.exports = {
  // ... 其他配置
  
  plugins: [
    new WebfunnyWebpackPlugin({
      url: 'http://localhost:8033/wfFile/api/sourceMapFile/upload',
      projectId: 'my_project_001',              // 项目 ID (必填)
      release: '1.0.0',                         // 版本号 (必填)
      projectName: '我的应用',                   // 项目名称（可选）
      urlPrefix: 'https://cdn.example.com',     // CDN 地址（可选）
      deleteAfterUpload: true,                  // 上传后删除 .map 文件（默认 true）
      silent: false,                            // 静默模式（默认 false）
      include: /\.map$/,                        // 包含的文件（默认所有 .map）
      exclude: null                             // 排除的文件（默认 null）
    })
  ]
};

使用动态版本号

const WebfunnyWebpackPlugin = require('webfunny-webpack-plugin');
const pkg = require('./package.json');

module.exports = {
  plugins: [
    new WebfunnyWebpackPlugin({
      url: process.env.WEBFUNNY_URL || 'http://localhost:8033/wfFile/api/sourceMapFile/upload',
      projectId: process.env.WEBFUNNY_PROJECT_ID,
      release: pkg.version,                     // 使用 package.json 的版本号
      projectName: pkg.name,                    // 使用 package.json 的项目名
      urlPrefix: process.env.CDN_URL,
      deleteAfterUpload: process.env.NODE_ENV === 'production' // 仅生产环境删除
    })
  ]
};

配置选项说明

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | url | string | ✅ | - | file_server 上传地址 | | projectId | string | ✅ | - | 项目 ID (webMonitorId) | | release | string | ✅ | - | 版本号（建议使用 package.json 的 version） | | projectName | string | ❌ | '' | 项目名称 | | urlPrefix | string | ❌ | '' | CDN 地址前缀 | | deleteAfterUpload | boolean | ❌ | true | 上传后是否删除 .map 文件 | | silent | boolean | ❌ | false | 是否静默模式（不输出日志） | | include | RegExp/Array | ❌ | /\.map$/ | 包含的文件匹配规则 | | exclude | RegExp/Array | ❌ | null | 排除的文件匹配规则 |

方式二：命令行使用

webfunny-cli upload \
  --url http://your-webfunny-server.com:8033/wfFile/api/sourceMapFile/upload \
  --api-key YOUR_PROJECT_ID \
  --app-version 1.0.0 \
  --project-name "My Application" \
  --url-prefix "https://cdn.example.com" \
  --dir ./dist

参数说明

| 参数 | 简写 | 必填 | 说明 | 示例 | |------|------|------|------|------| | --url | -u | ✅ | file_server 上传地址 | http://localhost:8033/wfFile/api/sourceMapFile/upload | | --api-key | -k | ✅ | 项目 ID (webMonitorId) | your_project_id | | --app-version | -v | ✅ | 应用版本号 | 1.0.0 | | --project-name | -n | ❌ | 项目名称 | "我的应用" | | --url-prefix | -p | ❌ | CDN 地址前缀 | https://cdn.example.com | | --dir | -d | ❌ | Source Map 文件目录 | ./dist (默认值) |

在 package.json 中使用

在你的项目 package.json 中添加脚本：

{
  "scripts": {
    "build": "webpack",
    "upload:sourcemap": "webfunny-cli upload -u http://your-server.com:8033/wfFile/api/sourceMapFile/upload -k YOUR_PROJECT_ID -v 1.0.0 -n \"My App\" -d ./dist"
  }
}

然后运行：

npm run upload:sourcemap

与构建工具集成

Webpack 构建后自动上传

在 package.json 中：

{
  "scripts": {
    "build": "webpack && npm run upload:sourcemap",
    "upload:sourcemap": "webfunny-cli upload -u http://your-server.com:8033/wfFile/api/sourceMapFile/upload -k $WEBFUNNY_PROJECT_ID -v $npm_package_version -n \"$npm_package_name\" -d ./dist"
  }
}

使用环境变量

创建 .env 文件（记得添加到 .gitignore）：

WEBFUNNY_URL=http://your-server.com:8033/wfFile/api/sourceMapFile/upload
WEBFUNNY_PROJECT_ID=your_project_id
WEBFUNNY_PROJECT_NAME=My Application
WEBFUNNY_URL_PREFIX=https://cdn.example.com

然后在脚本中使用：

webfunny-cli upload -u $WEBFUNNY_URL -k $WEBFUNNY_PROJECT_ID -v 1.0.0 -n "$WEBFUNNY_PROJECT_NAME" -p "$WEBFUNNY_URL_PREFIX"

示例

基本使用

webfunny-cli upload \
  -u http://localhost:8033/wfFile/api/sourceMapFile/upload \
  -k my_project_001 \
  -v 1.0.0 \
  -n "我的应用" \
  -p "https://cdn.example.com" \
  -d ./dist

输出示例：

  _    _  _____  ____   ____  _    _  _   _  _   _ __     __
 | |  | ||  ___||  _ \ |  __|| |  | || \ | || \ | |\ \   / /
 | |  | || |__  | |_) || |_  | |  | ||  \| ||  \| | \ \_/ / 
 | |  | ||  __| |  _ < |  _| | |  | || . ` || . ` |  \   /  
 | |__| || |___ | |_) || |   | |__| || |\  || |\  |   | |   
  \____/ |_____||____/ |_|    \____/ |_| \_||_| \_|   |_|   

Starting source map upload...
Target URL: http://localhost:8033/wfFile/api/sourceMapFile/upload
Source Directory: ./dist
App Version: 1.0.0
Found 5 source map files.
Uploading app.js.map... OK
Uploading vendor.js.map... OK
Uploading main.js.map... OK
Uploading runtime.js.map... OK
Uploading styles.css.map... OK

Summary: 5 successful, 0 failed.

Upload completed successfully!

使用场景对比

Webpack 插件 vs CLI 工具

| 场景 | 推荐方式 | 说明 | |------|---------|------| | 本地开发构建 | Webpack 插件 | 自动上传，无需额外操作 | | 生产环境构建 | Webpack 插件 | 集成到构建流程，一次完成 | | CI/CD 自动化 | CLI 工具 | 灵活控制上传时机 | | 补传历史文件 | CLI 工具 | 批量上传已有文件 |

相比手动上传的优势

自动化: 集成到构建流程，无需手动上传
批量处理: 一次性上传所有 Source Map 文件
版本管理: 自动关联应用版本
效率高: 比 Web 界面更快
可追溯: 上传记录可以通过日志查看
安全性: 上传后自动删除 .map 文件，避免泄露源码

常见问题

1. 上传失败怎么办？

检查以下几点：

Webfunny 服务器地址是否正确
API Key 是否有效
网络连接是否正常
Source Map 文件是否存在

2. 是否需要上传所有 .map 文件？

建议上传所有生产环境的 Source Map 文件，这样可以更好地定位错误。

3. 如何在 CI/CD 中使用？

方式一：使用 Webpack 插件（推荐）

在 webpack.config.js 中根据环境变量配置：

const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  plugins: [
    isProduction && new WebfunnyWebpackPlugin({
      url: process.env.WEBFUNNY_URL,
      projectId: process.env.WEBFUNNY_PROJECT_ID,
      release: process.env.CI_COMMIT_SHA || require('./package.json').version,
      projectName: process.env.WEBFUNNY_PROJECT_NAME,
      urlPrefix: process.env.CDN_URL
    })
  ].filter(Boolean)
};

在 CI/CD 中设置环境变量后，直接构建即可：

# .github/workflows/deploy.yml
- name: Build
  env:
    NODE_ENV: production
    WEBFUNNY_URL: ${{ secrets.WEBFUNNY_URL }}
    WEBFUNNY_PROJECT_ID: ${{ secrets.WEBFUNNY_PROJECT_ID }}
    WEBFUNNY_PROJECT_NAME: ${{ secrets.WEBFUNNY_PROJECT_NAME }}
    CDN_URL: ${{ secrets.CDN_URL }}
  run: npm run build

方式二：使用 CLI 工具

# .github/workflows/deploy.yml
- name: Build
  run: npm run build

- name: Upload Source Maps
  run: |
    npm install -g webfunny-webpack-plugin
    webfunny-cli upload \
      -u ${{ secrets.WEBFUNNY_URL }} \
      -k ${{ secrets.WEBFUNNY_PROJECT_ID }} \
      -v ${{ github.sha }} \
      -n "${{ secrets.WEBFUNNY_PROJECT_NAME }}" \
      -p "${{ secrets.WEBFUNNY_URL_PREFIX }}" \
      -d ./dist

License

ISC

贡献

欢迎提交 Issue 和 Pull Request！