浏览器插件FeHelper的学习：gulp基础、使用gulp构建项目

前言

最近在学习浏览器插件FeHelper，发现FeHelper使用了gulp来处理项目中的js、css等文件，因此打算学习一下。

参考：FeHelper、https://www.gulpjs.com.cn/

安装

安装 gulp 命令行工具

npm install --global gulp-cli
1

创建项目目录并进入

在项目目录下创建 package.json 文件

npm init
1

安装 gulp，作为开发时依赖项

npm install --save-dev gulp
1

检查 gulp 版本

gulp --version
1

创建 gulpfile 文件
利用任何文本编辑器在项目大的根目录下创建一个名为 gulpfile.js 的文件，并在文件中输入以下内容：

function defaultTask(cb) {
  // place code for your default task here
  cb();
}

exports.default = defaultTask
1
2
3
4
5
6

设置构建命令

// package.json
"scripts": {
  "build": "gulp"
},
1
2
3
4

创建任务

每个 gulp 任务（task）都是一个异步的 JavaScript 函数，此函数是一个可以接收 callback 作为参数的函数，或者是一个返回 stream、promise、event emitter、child process 或 observable (后面会详细讲解) 类型值的函数。

组合任务

Gulp 提供了两个强大的组合方法： series() 和 parallel()，允许将多个独立的任务组合为一个更大的操作。这两个方法都可以接受任意数目的任务（task）函数或已经组合的操作。series() 和 parallel() 可以互相嵌套至任意深度。

如果需要让任务（task）按顺序执行，请使用 series() 方法。

const { series } = require('gulp');

function transpile(cb) {
  // body omitted
  cb();
}

function bundle(cb) {
  // body omitted
  cb();
}

exports.build = series(transpile, bundle);
1
2
3
4
5
6
7
8
9
10
11
12
13

当 series() 或 parallel() 被调用时，任务（tasks）被立即组合在一起。这就允许在组合中进行改变，而不需要在单个任务（task）中进行条件判断。

const { series } = require('gulp');

function minify(cb) {
  // body omitted
  cb();
}


function transpile(cb) {
  // body omitted
  cb();
}

function livereload(cb) {
  // body omitted
  cb();
}

if (process.env.NODE_ENV === 'production') {
  exports.build = series(transpile, minify);
} else {
  exports.build = series(transpile, livereload);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

异步执行

当从任务（task）中返回 stream、promise、event emitter、child process 或 observable 时，成功或错误值将通知 gulp 是否继续执行或结束。如果任务（task）出错，gulp 将立即结束执行并显示该错误。

当使用 series() 组合多个任务（task）时，任何一个任务（task）的错误将导致整个任务组合结束，并且不会进一步执行其他任务。当使用 parallel() 组合多个任务（task）时，一个任务的错误将结束整个任务组合的结束，但是其他并行的任务（task）可能会执行完，也可能没有执行完。

返回stream
我们这里更多的是处理文件，因此其他返回类型就忽略，感兴趣的可以看官方文档：异步执行

const { src, dest } = require('gulp');

function streamTask() {
  return src('*.js')
    .pipe(dest('output'));
}

exports.default = streamTask;
1
2
3
4
5
6
7
8

使用 callback
如果任务（task）不返回任何内容，则必须使用 callback 来指示任务已完成。在如下示例中，callback 将作为唯一一个名为 cb() 的参数传递给你的任务（task）

function callbackTask(cb) {
  // `cb()` should be called by some async work
  cb();
}

exports.default = callbackTask;
1
2
3
4
5
6

处理文件

gulp 暴露了 src() 和 dest() 方法用于处理计算机上存放的文件。

• src() 接受 glob 参数，并从文件系统中读取文件然后生成一个 Node 流（stream）。它将所有匹配的文件读取到内存中并通过流（stream）进行处理。由 src() 产生的流（stream）应当从任务（task）中返回并发出异步完成的信号，就如 创建任务（task） 文档中所述。

• 流（stream）所提供的主要的 API 是 .pipe() 方法，用于连接转换流（Transform streams）或可写流（Writable streams）。

• dest() 接受一个输出目录作为参数，并且它还会产生一个 Node 流（stream），通常作为终止流（terminator stream）。当它接收到通过管道（pipeline）传输的文件时，它会将文件内容及文件属性写入到指定的目录中。

const { src, dest } = require('gulp');

exports.default = function() {
  return src('src/*.js')
    .pipe(dest('output/'));
}
1
2
3
4
5
6

向流中添加文件
src() 也可以放在管道（pipeline）的中间，以根据给定的 glob 向流（stream）中添加文件。新加入的文件只对后续的转换可用。如果 glob 匹配的文件与之前的有重复，仍然会再次添加文件。

这对于在添加普通的 JavaScript 文件之前先转换部分文件的场景很有用，添加新的文件后可以对所有文件统一进行压缩并混淆（uglifying）。

const { src, dest } = require('gulp');
const babel = require('gulp-babel');
const uglify = require('gulp-uglify');

exports.default = function() {
  return src('src/*.js')
    .pipe(babel())
    .pipe(src('vendor/*.js'))
    .pipe(uglify())
    .pipe(dest('output/'));
}
1
2
3
4
5
6
7
8
9
10
11

分阶段输出
dest() 可以用在管道（pipeline）中间用于将文件的中间状态写入文件系统。此功能可用于在同一个管道（pipeline）中创建未压缩（unminified）和已压缩（minified）的文件。

const { src, dest } = require('gulp');
const babel = require('gulp-babel');
const uglify = require('gulp-uglify');
const rename = require('gulp-rename');

exports.default = function() {
  return src('src/*.js')
    .pipe(babel())
    .pipe(src('vendor/*.js'))
    .pipe(dest('output/'))
    .pipe(uglify())
    .pipe(rename({ extname: '.min.js' }))
    .pipe(dest('output/'));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Glob 详解

glob 是由普通字符和/或通配字符组成的字符串，用于匹配文件路径。可以利用一个或多个 glob 在文件系统中定位文件。

src() 方法接受一个 glob 字符串或由多个 glob 字符串组成的数组作为参数，用于确定哪些文件需要被操作。glob 或 glob 数组必须至少匹配到一个匹配项，否则 src() 将报错。当使用 glob 数组时，将按照每个 glob 在数组中的位置依次执行匹配 - 这尤其对于取反（negative） glob 有用。

*
在一个字符串片段中匹配任意数量的字符，包括零个匹配。对于匹配单级目录下的文件很有用。

**
在多个字符串片段中匹配任意数量的字符，包括零个匹配。 对于匹配嵌套目录下的文件很有用。请确保适当地限制带有两个星号的 glob 的使用，以避免匹配大量不必要的目录。

!
由于 glob 匹配时是按照每个 glob 在数组中的位置依次进行匹配操作的，所以 glob 数组中的取反（negative）glob 必须跟在一个非取反（non-negative）的 glob 后面。第一个 glob 匹配到一组匹配项，然后后面的取反 glob 删除这些匹配项中的一部分。如果取反 glob 只是由普通字符组成的字符串，则执行效率是最高的。

['script/**/*.js', '!scripts/vendor/']
1

插件

这块不介绍了，相应的插件可以在npm仓库中搜索gulp

文件监控

gulp api 中的 watch() 方法利用文件系统的监控程序（file system watcher）将 globs 与 任务（task） 进行关联。它对匹配 glob 的文件进行监控，如果有文件被修改了就执行关联的任务（task）。如果被执行的任务（task）没有触发 异步完成 信号，它将永远不会再次运行了。

const { watch, series } = require('gulp');

function clean(cb) {
  // body omitted
  cb();
}

function javascript(cb) {
  // body omitted
  cb();
}

function css(cb) {
  // body omitted
  cb();
}

// 可以只关联一个任务
watch('src/*.css', css);
// 或者关联一个任务组合
watch('src/*.js', series(clean, javascript));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

初次执行
调用 watch() 之后，关联的任务（task）是不会被立即执行的，而是要等到第一次文件修之后才执行。
如需在第一次文件修改之前执行，也就是调用 watch() 之后立即执行，请将 ignoreInitial 参数设置为 false。

const { watch } = require('gulp');

// 关联的任务（task）将在启动时执行
watch('src/*.js', { ignoreInitial: false }, function(cb) {
  // body omitted
  cb();
});
1
2
3
4
5
6
7

参考FeHelper配置自己的项目

创建目录
在项目根目录下创建app和output 文件夹，app存放插件的相关代码、文件；output存放打包后的输出文件

创建一个基础的插件项目
在app文件夹下创建一个基础的插件项目。这块不说了，不会的可以看我之前的文章。

• css 用于存放插件需要的样式
• img 用于存放插件需要的图片、图标
• js 用于存放插件的相应逻辑
• vendor 用于存放使用到的库，比如jQuery、uikit
• manifest.json 插件的配置文件
• popup.html 点击插件弹窗的界面

本地加载
本地加载一下，测试项目能否正常运行

配置gulp

//引入gulp
let gulp = require('gulp');
//用于删除文件、文件夹
let clean = require('gulp-clean');
//用于复制文件
let copy = require('gulp-copy');
//用于压缩
let zip = require('gulp-zip');
// 用于文件压缩
let uglifyjs = require('gulp-uglify-es').default;
//用于压缩css
let uglifycss = require('gulp-uglifycss');
//用于压缩html
let htmlmin = require('gulp-htmlmin');
//用于压缩json
let jsonmin = require('gulp-jsonminify');
// node的文件模块
let fs = require('fs');
//用于处理文件流
let through = require('through2');
// 管道
let path = require('path');
//用于获取文件字节数
let pretty = require('pretty-bytes');
//用于使用shell脚本
let shell = require('shelljs');
//按指定顺序运行一系列 gulp 任务
let runSequence = require('run-sequence');
//这是为了扩展 gulp.watch（event）。有些任务错误可能导致被终止，使用可以解决问题。
let watchPath = require('gulp-watch-path');
//回调
let gcallback = require('gulp-callback');


// 创建清理任务，使output文件不可读，立即清理
gulp.task('clean', () => {
    return gulp.src('output', {read: false}).pipe(clean({force: true}));
});

//将apps文件夹下的图片复制到output文件夹下
gulp.task('copy', () => {
    return gulp.src(['apps/**/*.{gif,png,jpg,jpeg}']).pipe(copy('output'));
});

//将apps文件夹下的json文件压缩并写入到output/apps下
gulp.task('json', () => {
    return gulp.src('apps/**/*.json').pipe(jsonmin()).pipe(gulp.dest('output/apps'));
});

//将apps文件夹下的html，去除空格压缩写入到output/apps下
gulp.task('html', () => {
    return gulp.src('apps/**/*.html').pipe(htmlmin({collapseWhitespace: true})).pipe(gulp.dest('output/apps'));
});

// 合并 & 压缩 js
gulp.task('js', () => {
    let jsMerge = () => {
        return through.obj(function (file, enc, cb) {
            //将文件转化为utf8格式
            let contents = file.contents.toString('utf-8');

            //下面的不清是干嘛的
            let tpl = 'let #VARNAME# = (function(module){ #CODES# ; return module.exports; })({exports:{}});\r\n';

            let merge = (fp, fc) => {
                let js = {};

                let rfc = fc.replace(/Tarp\.require\(\s*(['"])(.*)\1\s*\)/gm, function (frag, $1, mod, $2, code) {
                    let mp = path.resolve(fp, '../' + mod + (/\.js$/.test(mod) ? '' : '.js'));
                    let mc = fs.readFileSync(mp).toString('utf-8');

                    frag = frag.replace(/[^\w]/g, '').replace('Tarprequire', 'TR');
                    js[frag] = merge(mp, mc);
                    return frag;
                });

                return Object.keys(js).map(k => {
                    return tpl.replace('#VARNAME#', k).replace('#CODES#', () => js[k]);
                }).join('; ') + rfc;
            };

            contents = merge(file.path, contents);
            file.contents = new Buffer(contents);
            this.push(file);
            return cb();
        })
    };
    //将apps文件下的js文件进行合并、压缩，最后写入到output/apps
    return gulp.src('apps/**/*.js').pipe(jsMerge()).pipe(uglifyjs()).pipe(gulp.dest('output/apps'));
});

// 合并 & 压缩 css
gulp.task('css', () => {

    let cssMerge = () => {
        return through.obj(function (file, enc, cb) {
            let contents = file.contents.toString('utf-8');

            let merge = (fp, fc) => {
                return fc.replace(/\@import\s+(url\()?\s*(['"])(.*)\2\s*(\))?\s*;?/gm, function (frag, $1, $2, mod) {
                    let mp = path.resolve(fp, '../' + mod + (/\.css$/.test(mod) ? '' : '.css'));
                    let mc = fs.readFileSync(mp).toString('utf-8');
                    return merge(mp, mc);
                });
            };

            contents = merge(file.path, contents);
            file.contents = new Buffer(contents);
            this.push(file);
            return cb();
        })
    };
     
   // 处理css文件 
    return gulp.src('apps/**/*.css').pipe(cssMerge()).pipe(uglifycss()).pipe(gulp.dest('output/apps'));
});


// 清理冗余文件，并且打包成zip，发布到chrome webstore
gulp.task('zip', () => {

    // 读取manifest文件
    let pathOfMF = './output/apps/manifest.json';
    let manifest = require(pathOfMF);

    // background、content-script中的文件，可以作为例外
    // let excludes = manifest.background.scripts.concat(manifest.content_scripts.map(cs => {
    //     return cs.js.join(',');
    // }).join(',').split(','));

    //这块 v2和v3版本不一样，模仿上面的进行修改
    let excludes = manifest.background.service_worker.concat(manifest.content_scripts.map(cs => {
        return cs.js.join(',');
    }).join(',').split(','));

    // ============冗余文件清理================================================
    shell.cd('output/apps');
    let fileList = shell.find('./').filter(file => {
        let included = 'yes';
        if (file.match(/\.css$/) && !/index\.css$/.test(file)) {
            included = shell.grep('-l', file, './**/*.{css,html,js}').stdout;
        } else if (file.match(/\.js$/) && !/index\.js$/.test(file)) {
            included = shell.grep('-l', file.replace(/\.js$/, ''), './**/*.{html,js}').stdout;
        }

        // 如果没有搜索到，再尝试下在js、css文件的当前目录下搜寻
        if (!included.trim().length && /\.(js|css)$/.test(file)) {
            let arr = file.split(/\//);
            let filename = arr.splice(-1);
            let dirname = arr.join('/');

            included = shell.grep('-l', filename, (dirname || '.') + '/*.{html,js,css}').stdout;
        }

        return !included.trim().length;
    });
    fileList = fileList.filter(f => excludes.indexOf(f) === -1);
    fileList.forEach(f => {
        shell.rm('-rf', f);
        console.log(new Date().toLocaleString(), '> 清理掉冗余文件：', f);
    });
    shell.cd('../../');

    // web_accessible_resources 中也不需要加载这些冗余的文件了
    //用于指定插件中的哪些资源开源被网页和其他扩展访问到，v2和v3有些不一样，并且我这里没有用到，因此注释掉
    //manifest.web_accessible_resources = manifest.web_accessible_resources.filter(f => fileList.indexOf(f) === -1);
    manifest.name = manifest.name.replace('-Dev', '');
    fs.writeFileSync(pathOfMF, JSON.stringify(manifest));

    // ============压缩打包================================================
    //压缩打包的代码有问题，没想明白如何修改，就删除了，只是最后不会生成压缩包而已
});

//打包发布到火狐，平常一般用chrom和edge，因此这块不用了，有用到的可以参考fehelper

//构建
gulp.task('default', ['clean'], () => {
    runSequence(['copy', 'css', 'js', 'html', 'json'], 'zip');
});

// 将apps文件下的文件同步写入到output/apps
gulp.task('sync', () => {
    gulp.src('apps/**/*').pipe(gulp.dest('output/apps'));
});

// 开发过程中用，相当于热更新，不用每次改完都要到浏览器里重新加载一下扩展
gulp.task('watch', () => {
    gulp.watch('apps/**/*.*', (event) => {
        let wp = watchPath(event, './', './output');
        gulp.src(wp.srcPath).pipe(copy('output')).pipe(gcallback(() => {
            console.log(new Date().toLocaleString(), '> 文件发生变化，已编译：', wp.srcPath);
        }));
    });
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194

使用

之前在package.json 里添加了打包命令，现在再添加开始时的命令

{
  "name": "chrome-juqery",
  "version": "1.0.0",
  "description": "基于jQuery开发chrom插件的项目",
  "main": "index.js",
  "scripts": {
    "watch": "gulp watch",
    "build": "gulp"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "gulp": "^3.9.1",
    "gulp-callback": "0.0.3",
    "gulp-clean": "^0.4.0",
    "gulp-copy": "^1.1.0",
    "gulp-htmlmin": "^4.0.0",
    "gulp-jsonminify": "^1.1.0",
    "gulp-uglify-es": "^1.0.1",
    "gulp-uglifycss": "^1.0.9",
    "gulp-watch-path": "^0.1.0",
    "gulp-zip": "^4.1.0",
    "pretty-bytes": "^4.0.2",
    "run-sequence": "^2.2.1",
    "shelljs": "^0.8.1"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

使用

• npm install 下载响应依赖
• npm run watch 进行本地开发
• npm run build 插件打包

问题：

查了下原因是gulp版本与node版本不兼容的问题，网上解决方案大体两种：
1、降低node版本，这里我们使用nvm将node版本切换到11

不清除nvm如何使用的可以看：使用nvm实现Windows下多个node版本之间的切换

2、修改package.json，修改完如下

{
  "name": "chrome-juqery",
  "version": "1.0.0",
  "description": "基于jQuery开发chrom插件的项目",
  "main": "index.js",
  "scripts": {
    "watch": "gulp watch",
    "build": "gulp",
    "preinstall": "npx npm-force-resolutions"
  },
  "resolutions": {
    "graceful-fs": "^4.2.4"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "gulp": "^3.9.1",
    "gulp-callback": "0.0.3",
    "gulp-clean": "^0.4.0",
    "gulp-copy": "^1.1.0",
    "gulp-htmlmin": "^4.0.0",
    "gulp-jsonminify": "^1.1.0",
    "gulp-uglify-es": "^1.0.1",
    "gulp-uglifycss": "^1.0.9",
    "gulp-watch-path": "^0.1.0",
    "gulp-zip": "^4.1.0",
    "pretty-bytes": "^4.0.2",
    "run-sequence": "^2.2.1",
    "shelljs": "^0.8.1"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

我这里采用的第二种，最后效果如下图

在本地加载时还是加载apps目录，当内容发生改变后会重新构建，并在控制台里打印，浏览器插件也会被更新。

打包

npm run build
1

我们加载一下output目录下的apps，确认一下插件是否可以正常运行。我这里是可以正常运行的

项目地址
https://gitee.com/idonotyou/chrome-jquery ，感觉还不错的话点个收藏。