vite-plugin-monkey/README_zh.md at main · lisonge/vite-plugin-monkey

一个 vite 插件，用来辅助开发 Tampermonkey 和 Violentmonkey 和 Greasemonkey 的脚本

特性

支持 Tampermonkey 和 Violentmonkey 和 Greasemonkey 的脚本辅助开发
打包自动注入脚本配置头部注释
当第一次启动或脚本配置注释改变时自动在默认浏览器打开脚本
友好的利用 @require 配置库的 cdn 的方案，大大减少构建脚本大小
完全的 Typescript 和 Vite 的开发体验，比如模块热替换,秒启动

安装

pnpm add -D vite-plugin-monkey

配置

MonkeyOption

export interface MonkeyOption {
  /**
   * 脚本文件的入口路径
   */
  entry: string;
  userscript: MonkeyUserScript;
  format?: Format;
  server?: {
    /**
     * 当 第一次启动 或 脚本配置注释改变时 自动在默认浏览器打开脚本
     * @default true
     */
    open?: boolean;

    /**
     * 开发阶段的脚本名字前缀，用以在脚本安装列表里区分构建好的脚本
     * @default 'dev:'
     */
    prefix?: string | ((name: string) => string);
  };
  build?: {
    /**
     * 打包构建的脚本文件名字 应该以 '.user.js' 结尾
     * @default (package.json.name||'monkey')+'.user.js'
     */
    fileName?: string;

    /**
     * @example
     * {
     *  vue:'Vue',
     *  // 你需要额外设置脚本配置 userscript.require = ['https://unpkg.com/[email protected]/dist/vue.global.js']
     *  vuex:['Vuex', 'https://unpkg.com/[email protected]/dist/vuex.global.js'],
     *  // 插件将会自动注入 cdn 链接到 userscript.require
     *  vuex:['Vuex', (version)=>`https://unpkg.com/[email protected]${version}/dist/vuex.global.js`],
     *  // 相比之前的，加了版本号，当依赖升级的时候，cdn 链接自动改变
     *  vuex:['Vuex', (version, name)=>`https://unpkg.com/${name}@${version}/dist/vuex.global.js`],
     *  // 还可以加依赖名字,不过各个依赖的 cdn basename 都不尽一致, 导致可能没什么用
     * }
     *
     */
    externalGlobals?: Record<
      string,
      string | [string, string | ((version: string, name: string) => string)]
    >;

    /**
     * 自动识别代码里用到的 浏览器插件api，然后自动配置 GM_* 或 GM.* 函数到脚本配置注释头
     *
     * 识别依据是判断代码文本里有没有特定的函数名字
     * @default true
     */
    autoGrant?: boolean;
  };
}

MonkeyUserScript

/**
 * 综合后的脚本配置, 合并了来自 Greasemonkey, Tampermonkey, Violentmonkey, Greasyfork 的元数据
 */
export type MonkeyUserScript = GreasemonkeyUserScript &
  TampermonkeyUserScript &
  ViolentmonkeyUserScript &
  GreasyforkUserScript &
  MergemonkeyUserScript;

Format

/**
 * 格式化脚本头配置注释
 */
export type Format = {
  /**
   * @description 对齐的空格数量，请注意，显示的时候，保证你的代码是等宽字体
   * @default 2, true
   */
  align?: number | boolean | AlignFunc;
};

// 自定义对齐函数
export type AlignFunc = (
  p0: [string, ...string[]][]
) => [string, ...string[]][];

例子

vite 非常容易上手，请直接看 test/example/vite.config.ts

例子中的构建产物在 test/example/dist/example-project.user.js

搭配 vue 使用的例子

https://github.com/lisonge/op-wiki-plus

注意

CSP

大多数情况下，此问题不会出现

在开发模式，我们的脚本需要在两个域之间工作，宿主域和本地开发服务器

如果宿主域启用了 CSP, 浏览器会拒绝加载宿主域以外的脚本，因此你必须关闭它，关闭方法如下

chrome - 安装浏览器插件 Disable Content-Security-Policy
edge - 安装浏览器插件 Disable Content-Security-Policy
firefox - 在 about:config 菜单项里，禁用配置 security.csp.enable

Polyfill

由于 vitejs/vite#1639, 你暂时不能使用 @vitejs/plugin-legacy

一种可行的方案是直接在 @require 加 cdn 去 polyfill

import { defineConfig } from 'vite';
import monkeyPlugin from 'vite-plugin-monkey';

export default defineConfig({
  plugins: [
    vue(),
    monkeyPlugin({
      userscript: {
        require: [
          // polyfill 全部
          'https://cdn.jsdelivr.net/npm/[email protected]/minified.js',
          // 或者使用 polyfill.io 智能 polyfill, 不过 polyfill.io 在大陆网络连通性很差, 几乎不能用
          // https://polyfill.io/v3/polyfill.min.js
        ],
      },
    }),
  ],
});