使用 Vite 外掛開發構建 Tampermonkey 使用者指令碼

SakuraYumine發表於2022-05-24
Vite指令碼

起因

一直以來，我都是直接在瀏覽器 Tampermonkey 擴充套件頁面直接新建使用者指令碼來開發的：

圖 1

對於一些簡單的指令碼，這沒有什麼問題，即改即看。但當程式碼多了以後問題就來了，自帶編輯器開發體驗確實不太舒服，沒有格式化，沒有程式碼補全，無法模組化編寫程式碼等等，這時候我就想尋找一個打包方案，讓我們可以在自己的編輯器如 VSCode 裡開發，這樣就可以充分利用前端工程化的便利，提升開發體驗。

常見的打包工具比如 webpack、parcel、rollup 等，首先排除 webpack（笑），然後試了下 parcel，效果不太理想，之後試了 rollup 感覺還可以。轉眼想到要用 vue 開發，那就直接上 vite 吧 ?，vite 也是用 rollup 來打包生產程式碼的。

直接開啟 npm，看看有沒有人造輪子，然後發現下面幾個包：

  • gorilla (rollup 外掛）
  • vite-plugin-tampermonkey
  • vite-plugin-monkey

這幾個都符合基本需求，其中 gorilla 不能打包樣式，另外兩個外掛都差不多，選了 vite-plugin-tampermonkey 進行改造。

修改後的外掛： Github | npm

外掛特點

  • 通過單獨的配置檔案或者 package.json 中的 tmHeader 欄位來配置 Tampermonkey 的 Userscript Header
  • 構建生產時支援自動分析程式碼用到的 grant
  • 開發模式時預設匯入所有 grant，並且把所有的 grant 方法加入到 unsafeWindow
  • 可通過簡單配置，把引入的外部包 require 化，自動引入 jsdelivr CDN ，詳情見下面的外掛配置

開始之前

Vite 官方中文文件

Tampermonkey 文件

gorilla

vite-plugin-tampermonkey

vite-plugin-monkey

初始化專案

相容性注意
Vite 需要 Node.js 版本 >= 12.0.0。然而，有些模板需要依賴更高的 Node 版本才能正常執行，當你的包管理器發出警告時，請注意升級你的 Node 版本。

使用 NPM:

$ npm create vite@latest

使用 Yarn:

$ yarn create vite

使用 PNPM:

$ pnpm create vite

按需選擇框架

圖 3

推薦使用 TypeScript

圖 4

然後到專案目錄開始安裝依賴

外掛使用

安裝

yarn add vite-plugin-tm-userscript -D
# OR
npm install vite-plugin-tm-userscript -D

配置 vite.config.ts

import { defineConfig } from 'vite'
import Userscript from 'vite-plugin-tm-userscript'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    Userscript({
      externalGlobals: ['vue']
    })
  ]
})

配置 Userscript Header

有四種方式來配置 Userscript Header, 優先順序如下所示

  1. header.config.json
  2. header.config.js
  3. header.config.txt
  4. package.json 中的 tmHeader 欄位

其中 header.config.txt 使用 Tampermonkey 頭部註釋配置，不會經過處理，直接插入指令碼頭部作為 Header 使用

其他三種格式按 json 格式配置，多個屬性配置如 match 用陣列表示，經過處理自動新增 grant 與 require

示例配置見 example/header.config.js

使用 js 檔案來配置的好處是可以有自動補全：

圖 5

具體屬性配置見 Tampermonkey 文件

外掛配置

export interface TMPluginOptions {
  entry?: string;
  autoGrant?: boolean;
  externalGlobals?: string[] | Record<string, string | string[]>;
}

externalGlobals

配置外部包，比如 vue，axios 等，減少打包體積，並且會自動宣告 require ，如下配置：

三種配置形式，可自定義 CDN，不配置 CDN 的話預設使用 jsdelivr CDN

// 1
TMPlugin({
  externalGlobals: ['jquery']
})

// 2
TMPlugin({
  externalGlobals: {
    'jquery': 'jQuery'
  }
})

// 3
TMPlugin({
  externalGlobals: {
    'jquery': ['jQuery', 'https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.min.js']
  }
})

// =>

return {
  rollupOptions: {
    external: ['jquery']
    output: {
      globals: {
        jquery: 'jQuery'
      }
    }
  }
}

// @require https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.min.js

autoGrant

boolean 型別，預設為 true

自動分析程式碼中使用的 Tampermonkey 的 grant，並加入 Userscript Header 宣告中

entry

入口檔案，預設為 src/main.js 或者 src/main.ts

開發啟動

npm run dev 或 yarn dev 執行開發服務，然後點選下圖所示連結安裝

圖 6

生產打包

npm run build 或 yarn build 進行生產模式打包，打包檔案放在 dist 資料夾裡

然後可以釋出到外掛市場或者直接安裝到瀏覽器

示例

https://github.com/asadahimeka/vite-plugin-tm-userscript/tree/master/example

說明

vite 配置額外說明

生產構建模式將強制配置 config.build:

  • 構建的包名為 package.json 的 name （必須填寫）屬性的駝峰模式，構建的檔名也與其相關
  • 檔案打包格式為 iife，不壓縮，不分離 css 檔案
  • 額外配置了 rollupOptions，以支援其他功能

禁止 CSP(Content-Security-Policy)

在開發模式下，需要通過 script 標籤注入 vite 的指令碼，有些網站開啟了 CSP(Content-Security-Policy)，導致報錯，可以安裝 Chrome 外掛 Disable Content-Security-Policy 或者 Always Disable Content-Security-Policy，來禁止 CSP(Content-Security-Policy)，在開發時開啟外掛即可（其他時間記得關閉以保證網頁瀏覽的安全性）。

fin.

相關文章