Overview

JavaScript offers powerful array methods for various operations, some of which have similar names and functionalities.

In this article, I focus on the array methods prefixed with find- and explore their unique characteristics, comparing them with each other and also with other related array methods, to help JavaScript developers better distinguish and wield them.

Know your find-* array methods

JavaScript offers four array methods prefixed with find-:

• find()
• findLast()
• findIndex()
• findLastIndex()

These find-* array methods share three characteristics in syntax and return value.

They require a callback function as argument

For the find-* methods, the callback serves as a matching condition to check array elements with. When evaluated as truthy by the callback, the element is a match; when evaluated as falsy, it is a no-match.

They return a matched array element or its index when there is one

Let’s start with find() and findLast() first.

The two both return the first matched element no matter how many matches there are in the array.

They differ only in traversal direction: find() checks array elements from left to right while findLast() does so from right to left.

The example shows this directional difference. With the same array, find() returns a match at its beginning, but findLast() returns one that’s situated at the end.

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age === 10
const firstMatch = list.find(cb) // {name: 'A', age: 10}
const lastMatch = list.findLast(cb) // {name: 'C', age: 10}

We should beware of the type of array elements being checked. When an element is of a primitive type–be it a string, number, or boolean–find() and findLast() return a distinct copy of the match. Changing the copy doesn’t affect the source array at all.

const numbers = [1, 100, 200]

let match = numbers.find(number => number < 100)
match++
console.log(match) // 2 
console.log(numbers) // [1, 100, 200]

However, when an element is of a complex type, like an array or object, find() and findLast() return the match’s reference in memory. In the light of “copy by reference” of JavaScript, whatever changes made to the returned match are preserved in the source array.

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const match = list.find(obj => obj.age === 20)
match.age++

console.log(match) //  {name: 'B', age: 21}
console.log(list)  // [{name: 'A', age: 10}, 
                   // {name: 'B', age: 21}, 
                   // {name: 'C', age: 10}]
console.log(match === list[1]) // true

findIndex() and findLastIndex() return the index of the first match in the array, but they also differ in traversal direction: findIndex() runs from left to right whereas findLastIndex() runs from right to left.

We should note that, in whichever traversal direction the methods run, we always get an index number in the conventional left-to-right ordering.

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age === 10
const firstMatchIndex = list.findIndex(cb) // 0
const lastMatchIndex = list.findLastIndex(cb) // 2

They return undefined or -1 when no match is found in the array

If there’s not any array element matched, find() and findLast() return undefined, indicating that no such an element in the array meets the matching condition.

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age < 0

const firstMatch = list.find(cb) // undefined
const lastMatch = list.findLast(cb) // undefined

On the other hand, findIndex() and findLastIndex() return -1, an impossible index number that falls out of the zero-based ordering for array elements. -1 is a conventional return value for array and string methods–for example, indexOf() and lastIndexOf()–when no match is found.

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age < 0
const firstMatchIndex = list.findIndex(cb) // -1
const lastMatchIndex = list.findLastIndex(cb) // -1

find-* methods and their characteristics

In brief, find-* array methods rely on the callback to evaluate every element in the array. They either return the first matched array element or its index. If there’s no match found, they either return undefined or -1 to indicate non-existence of such matches.

Other similar array methods

These find-* methods are not the only methods available in JavaScript arrays to find a matched element or its index. Let’s check out some other methods with similar functionality.

• find() and findLast() vs filter()

These three all require a callback function as the argument, and evaluate all the elements inside an array with it.

The major difference lies in their return values.

When a match is found in the array, find() and findLast() return only the first matched element, depending on the traversal direction taken. filter() returns a new array containing all matched elements.

const numbers = [-10, -1, 0, 1, 10]

const cb = number => number > 0

const firstMatch = numbers.find(cb)   // 1
const lastMatch = numbers.findLast(cb) // 10
const allMatches = numbers.filter(cb)  // [1, 10]

When no match is found, find() and findLast() return undefined, while filter() returns an empty array.

const numbers = [-10, -1, 0, 1, 10]

const cb = number => number > 100

const firstMatch = numbers.find(cb)   // undefined
const lastMatch = numbers.findLast(cb) // undefined
const allMatches = numbers.filter(cb)  // []

• findIndex() vs indexOf()

These two are close in their names and both return an index number. However, they take different types of argument to fulfill their job.

findIndex() requires a callback function but indexOf() requires just a value. By passing in a value to indexOf(), we are asking if there is any element in the array that is identical to the value (in the sense of strict equality).

If there is such a match, indexOf() returns the match’s index, that is, its position in the array. If not, they both return -1.

const numbers = [-10, -1, 0, 1, 10]

const matchId1 = numbers.indexOf(0) // 2
const matchId2 = numbers.findIndex(number => number === 0) // 2

const noMatchId1 = numbers.indexOf(100) // -1
const noMatchId2 = numbers.findIndex(number => number === 100) // -1

• findLastIndex() vs lastIndexOf()

They are the exact twin of the findIndex() and indexOf() methods, despite the fact that they traverse over an array in the opposite direction. findLastIndex() requires a callback argument whereas lastIndexOf() requires a value argument. They either return the index of the first match or -1 when there’s none.

const numbers = [-10, -1, 0, 1, 10]

const matchId1 = numbers.lastIndexOf(0) // 2
const matchId2 = numbers.findLastIndex(number => number === 0) // 2

const noMatchId1 = numbers.lastIndexOf(100) // -1
const noMatchId2 = numbers.findLastIndex(number => number === 100) // -1

Summary

The find-* array methods all require a callback to evaluate every element in an array, allowing us to search through an array flexibly. When a match is found, they return the first matched array element or its index, or undefined or -1 when there’s no match.

We’ve also checked out some other similar array methods. filter() requires a callback to evaluate array elements too, but it returns an new array with all the elements that match.

indexOf() and lastIndexOf() require a value, not a callback, and return the index of the first match that’s strictly equal to the value.

概述

JavaScript 歷經多年演進，內建相當多的語法可供使用。然而，其中許多語法不僅名稱類似，甚至連使用方式也極為雷同。對於新手或有經驗的開發者來說，要分辨它們的差異並在適當時機使用並不是一件簡單的事。

本文聚焦在 JavaScript 的 find-* 陣列方法，接著再與其他名稱/使用方式相近的陣列方法相互比較，更能清楚判斷應該使用哪個語法。

認識 find-* 的陣列方法

JavaScript 有以下 find 開頭的陣列方法：

• find()
• findLast()
• findIndex()
• findLastIndex()

這些 find-* 方法的特性如下：

• 傳入 callback 函式作為 argument

callback 函式負責判斷陣列元素是否符合條件。如果陣列元素放入 callback 的執行結果為 truthy 值，代表符合條件。如果執行結果為 falsy 值，代表不符合條件。

• 發現符合條件的陣列元素，則回傳元素或元素的 index

當有 n 個陣列元素符合條件時 (n >= 1)，find() 和 findLast() 會回傳第一個符合條件的陣列元素。

差別在於 find() 從陣列開頭 (最左側) 開始遍歷陣列元素，而 findLast() 則是從陣列尾端 (最右側) 開頭遍歷元素：

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age === 10

const firstMatch = list.find(cb) // {name: 'A', age: 10}
const lastMatch = list.findLast(cb) // {name: 'C', age: 10}

當元素是字串、數字、布林值等原始型別的值，find() 和 findLast() 會回傳元素的複本 copy。修改複本並不會影響到原來的陣列：

const numbers = [1, 100, 200]

let match = numbers.find(number => number < 100)

match++

console.log(match) // 2 
console.log(numbers) // [1, 100, 200]

當元素是陣列或物件之類的複雜型別，則是回傳元素的 reference (記憶體位址)；要注意的是，一旦修改了這類元素的內容，也會同時影響到原來的陣列：

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const match = list.find(obj => obj.age === 20)

match.age++

console.log(match) //  {name: 'B', age: 21}

console.log(list)  // [{name: 'A', age: 10}, 
                   // {name: 'B', age: 21}, 
                   // {name: 'C', age: 10}]

console.log(match === list[1]) // true

與 find() 和 findLast() 類似，findIndex() 和 findLastIndex() 則會分別從陣列開頭或尾端開始遍歷陣列，只是它們的回傳值是第一個符合條件的元素的 index。雖然遍歷陣列的方式不同，但回傳的 index 和一般認知的 index 一樣，都是由左至右、從 0 開始編號：

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age === 10

const firstMatchIndex = list.findIndex(cb) // 0
const lastMatchIndex = list.findLastIndex(cb) // 2

• 找不到符合條件的陣列元素，則回傳 undefined 或 -1
  如果所有陣列元素皆不符合 callback 的指定條件 (皆為 falsy 值)，find() 和 findLast() 方法則會回傳 undefined，代表找不到符合的元素：

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age < 0

const firstMatch = list.find(cb) // undefined
const lastMatch = list.findLast(cb) // undefined

findIndex() 和 findLastIndex() 則回傳 -1。由於找不到符合的元素，自然也沒有對應的 index，就以 -1 代表不可能出現的 index：

const list = [{name: 'A', age: 10}, 
              {name: 'B', age: 20}, 
              {name: 'C', age: 10}]

const cb = member => member.age < 0

const firstMatchIndex = list.findIndex(cb) // -1
const lastMatchIndex = list.findLastIndex(cb) // -1

小整理：

簡言之，find-* 陣列方法都是為了「找到符合判斷條件的元素」或「找到符合判斷條件的元素的 index」，需要傳入 callback 函式作為判斷條件。
find-* 方法翻譯成自然語言的大致意義如下：

請依據條件 (callback 函式)，判斷陣列內是否有符合條件的元素。如果有的話，請回傳給我符合的第一個元素或是這個元素的 index。如果找不到符合的元素，請給我 undefined 或 -1。

其他相似的陣列方法

find-* 陣列方法能在陣列中找到符合條件的元素，但還有其他方法也有類似的作用。一起來認識之間的差異！

• find() 和 findLast() vs filter()

這三個陣列方法都需要傳入 callback 函式來判斷元素是否符合條件。主要差異在於它們的回傳值。

當存在符合條件的元素時，find() 和 findLast() 會直接回傳第一個符合的元素 (兩者遍歷陣列的方向不同)。filter() 則是回傳一個新陣列，內含所有符合條件的元素：

const numbers = [-10, -1, 0, 1, 10]

const cb = number => number > 0

const firstMatch = numbers.find(cb)   // 1
const lastMatch = numbers.findLast(cb) // 10
const allMatches = numbers.filter(cb)  // [1, 10]

當陣列中沒有符合條件的元素時，find() 和 findLast() 皆回傳 undefined，而 filter() 則回傳空陣列：

const numbers = [-10, -1, 0, 1, 10]

const cb = number => number > 100

const firstMatch = numbers.find(cb)   // undefined
const lastMatch = numbers.findLast(cb) // undefined
const allMatches = numbers.filter(cb)  // []

• findIndex() vs indexOf()

這兩個方法名稱非常相似，有如雙胞胎，而且都會回傳元素的 index。差別在於需要傳入的 argument 類型不同。findIndex() 需要傳入 callback 作為判斷條件，再回傳符合的元素 index。

indexOf() 的意義是在查詢「某個值在陣列中的 index 位置」。不須傳入任何條件，只需要傳入要找的值，就會確認陣列內有無嚴格意義上相等 (===) 的元素，接著回傳該元素的 index (在陣列內的位置)。

當找不到符合的元素時，這兩個方法都會回傳 -1。

const numbers = [-10, -1, 0, 1, 10]

const matchId1 = numbers.indexOf(0) // 2
const matchId2 = numbers.findIndex(number => number === 0) // 2

const noMatchId1 = numbers.indexOf(100) // -1
const noMatchId2 = numbers.findIndex(number => number === 100) // -1

• findLastIndex() vs lastIndexOf()

這是另一組名稱相似的雙胞胎方法，同樣都會回傳符合元素的 index；找不到符合的元素時，都會回傳 -1。

差異也和上一組雙胞胎方法一樣：findLastIndex() 需要 callback 函式作為判斷條件，而 lastIndex() 只需傳入值。

const numbers = [-10, -1, 0, 1, 10]

const matchId1 = numbers.lastIndexOf(0) // 2
const matchId2 = numbers.findLastIndex(number => number === 0) // 2

const noMatchId1 = numbers.lastIndexOf(100) // -1
const noMatchId2 = numbers.findLastIndex(number => number === 100) // -1

結論

本文以 find-* 方法為主，介紹其特色：

• find-* 方法皆需要傳入 callback 函式作為判斷條件，接著回傳第一個符合的元素 (或元素 index)。

透過 callback 函式，也方便我們自訂各種條件找到符合的元素。

另外，也與名稱、作用雷同的其他陣列語法一齊比較。透過比較掌握彼此間的相似及相異處：

• filter() 同樣需要傳入 callback 函式作為判斷條件，但回傳值是一個新的陣列，陣列內會有所有符合條件的元素。

• indexOf() 和 lastIndexOf() 則是需要傳入一個值，確認陣列中是否有嚴格相等的值，接著回傳相等值的所在位置 (index)。

拆分 Gulp 任務到不同檔案，管理更方便！

概述

當專案架構變複雜，gulpfile.js 裡的公開及私有任務數量也更加龐大，在維護和執行指令時更加不便。

可以將 gulpfile.js 依照功能、專案或其他分類拆分成多個檔案，達到關注點分離 (separation of concerns) 的目的。日後維護和執行會更加輕鬆。

本文會介紹如何拆分 gulpfile.js 檔案及如何執行任務：

• 依功能拆分為多個 gulpfile.js 檔案
• 依專案拆分 gulpfile.js 檔案

依功能拆分為多個 gulpfile.js 檔案

當 Gulp 任務數量眾多，可以將任務拆分成多個模組檔案進行管理，例如將 JavaScript、CSS 和 HTML 的處理任務放在不同模組檔案中。

如此一來，不僅方便新增、修改和搜尋任務。要使用任務時，再將模組檔案的任務集中匯入到相同的 index.js 檔案即可。

接下來，會為範例專案中的 JavaScript、CSS 和 HTML 檔案各自建立壓縮內容的任務。

範例架構如下：

|-- 專案/
    |-- index.html
    |-- css/
        |-- index.css
        |-- mobile.css
    |-- js/
        |-- index.js

1. 安裝要使用的套件及外掛程式：

npm install --save-dev gulp gulp-cssnano gulp-htmlmin gulp-uglify

2. 在專案根目錄處建立名為 gulpfile.js 資料夾，在裡面新增 index.js 檔案及其他存放任務的模組檔案。新的專案結構如下：

|-- 專案/
    |-- index.html
    |-- css/
        |-- index.css
        |-- mobile.css
    |-- js/
        |-- index.js
    |-- gulpfile.js/
        |-- index.js
        |-- cssTasks.js
        |-- jsTasks.js
        |-- htmlTasks.js

對於 Gulp 來說，gulpfile.js 資料夾內的 index.js 檔案等於平常使用的 gulpfile.js 檔案，都是 Gulp 存取任務函式的唯一進入點。

3. 在個別模組檔案內建立壓縮任務。

// cssTasks.js
const {src, dest} = require('gulp')
const cssnano = require('gulp-cssnano')

exports.minifyCSS = function(){
    return src('css/*.css')
        .pipe(cssnano())
        .pipe(dest('dist/css'))
}

// jsTasks.js
const {src, dest} = require('gulp')
const uglify = require('gulp-uglify')

exports.uglifyJS = function(){
    return src('js/*.js')
        .pipe(uglify())
        .pipe(dest('dist/js'))
}

// htmlTasks.js
const {src, dest} = require('gulp')
const htmlmin = require('gulp-htmlmin')

exports.minifyHTML = function(){
  return src("*.html")
    .pipe(htmlmin({ collapseWhitespace: true }))
    .pipe(dest("dist/"));
}

要注意的是，在模組檔案內指定輸入和輸出的檔案路徑時，必須以 gulpfile.js 資料夾為基準點，而不是以模組檔案為基準點。

換句話說，要將 gulpfile.js 資料夾當成是一個單純的檔案，如同未拆分時的 gulpfile.js 檔案。所有的路徑皆從這個資料夾為基準點。

4. 將模組檔案的任務集中匯入至 index.js。在 index.js 中可以直接使用匯入的任務，或是重新進行組裝建立新的任務。

// index.js

const { src, dest, parallel, watch } = require("gulp");
const { minifyCSS } = require("./cssTasks");
const { minifyHTML } = require("./htmlTasks");
const { uglifyJS } = require("./jsTasks");

exports.default = function () {
  watch(
    ["*.html", "js/*.js", "css/*.css"],
    { ignoreInitial: false },
    parallel(minifyCSS, minifyHTML, uglifyJS)
  );
};

此處利用匯入的任務建立新的監聽任務，再匯出任務以供執行。

5. 在終端機輸入 Gulp 指令就能執行任務：

gulp

依專案拆分 gulpfile.js 檔案

另一種可能的情況是大專案資料夾內有多個小專案資料夾。小專案各自有自己的 Gulp 任務可以使用。所有小專案的Gulp 任務皆集中在大專案根目錄的 gulpfile.js 檔案內。

|-- 大專案/
    |-- package.json
    |-- gulpfile.js
    |-- 小專案1/
        |-- index.html
        |-- styles.css
        |-- index.js
        |-- ...
    |-- 小專案2/
    |-- 小專案3/

要為某個小專案新增、修改任務時，很可能要連帶調整其他小專案的 Gulp 任務，處理起來可能不方便。當小專案數量變多時，更加不輕鬆且容易出錯。

這時候可以將大專案的 gulpfile.js 拆分至各個小專案內。讓小專案有獨立的 gulpfile.js 檔案。

執行小專案時，只需要用到小專案的 gulpfile.js 檔案，不會和其他小專案共用任務。

|-- 大專案/
    |-- package.json
    |-- 小專案1/
        |-- gulpfile.js
        |-- index.html
        |-- styles.css
        |-- index.js
        |-- ...
    |-- 小專案2/
        |-- gulpfile.js
        |-- ...
    |-- 小專案3/
        |-- gulpfile.js
        |-- ...

在小專案 gulpfile.js 檔案內撰寫任務的方式，完全與為單一專案撰寫 Gulp 任務的方式相同。

差別在於執行 Gulp 任務的方式。如果要執行某個小專案的 Gulp 任務，有兩種方式：

• 在小專案根目錄執行 Gulp 指令
• 在大專案根目錄執行 Gulp 指令

在小專案根目錄執行 Gulp 任務頗符合直覺。然而，如果同時有多個小專案要執行 Gulp 指令，就得反覆切換資料夾，不是那麼方便。

在大專案根目錄執行 Gulp 指令會是更方便的方式！

Gulp CLI 內建 --gulpfile [檔案路徑] 指令，能夠選擇特定路徑的 gulpfile.js 執行：

查看小專案 1 的 Gulp 任務清單：

gulp --tasks --gulpfile ./小專案1/gulpfile.js

執行小專案 1 的預設任務：

# OK
gulp --gulpfile ./小專案1/gulpfile.js

或

# OK
gulp default --gulpfile ./小專案1/gulpfile.js

執行小專案 1 的 minifyCSS 任務：

gulp minifyCSS --gulpfile ./小專案1/gulpfile.js

此時 Gulp 指令已經變長不少。建議在大專案根目錄的 package.json 中建立對應的 npm 指令，不僅可以集中管理，執行時更方便。

例如為小專案 1 及所有專案建立 build 任務：

// package.json

"scripts": {
    "build_p1": "gulp build --gulpfile ./小專案1/gulpfile.js",
    "build_all": "gulp build --gulpfile ./小專案1/gulpfile.js & gulp build --gulpfile ./小專案2/gulpfile.js & gulp build --gulpfile ./小專案3/gulpfile.js"
}

只需要在大專案根目錄執行 npm run build_p1 和 npm run build_all 就好，非常精簡！

結論

當 gulpfile.js 檔案的任務數量變多，維護難度增加時，可以依據不同功能或專案將任務拆分至不同檔案。

有兩種建議作法：

• 在 gulpfile.js 資料夾中，將任務拆分為不同的模組檔案，再將模組檔案匯入到相同的 index.js 檔案。
• 將任務拆分至多個 gulpfile.js 檔案，執行任務時指令加上 --gulpfile 和對應的檔案路徑。

這樣一來管理 Gulp 任務時會更加方便，也減少出錯的可能。

參考資料

• Trouble with splitting gulpfile.js into multiple files in Gulp 4
• JavaScript and Gulpfiles | gulp.js
• Gulpv4 Splitting Up Gulpfile
• gulp-cli

認識 Gulp.js 系列

想要再多瀏覽 Gulp.js 4 相關教學，別錯過下列文章！

1. 認識 Gulp.js — 你的前端開發萬用刀
2. 認識 Gulp.js — 建立 Gulp 任務
3. 認識 Gulp.js — Gulp 任務的非同步特性
4. 認識 Gulp.js — 匯出及執行 Gulp 任務
5. 認識 Gulp.js — 建立監聽任務
6. 認識 Gulp.js — 拆分 Gulp 任務

監聽檔案變動，自動執行 Gulp 流程

概述

若要執行 Gulp 任務，通常要在終端機上手動輸入指令觸發。然而，開發時可能遇上需要反覆執行任務的情境，若是只能透過手動觸發，效率極低。

為了解決上述問題，Gulp 提供非常方便的監聽功能：Gulp 會監聽指定檔案，當檔案內容發生變動時，就會自動執行對應任務。

本文內容如下：

．認識監聽任務

．更多任務設定

．建立更複雜的監聽任務

．匯出和執行監聽任務

．用 chokidar 實例建立監聽任務 (不推薦)

．動手練習

認識監聽任務

Gulp 內建 watch 方法，用來建立監聽任務。當 Gulp 監聽到檔案發生指定的事件，就會立即執行對應任務。

watch 方法能夠監聽下列事件：

• add：新增檔案
• change：修改檔案
• unlink：移除檔案
• addDir：新增資料夾
• unlinkDir：移除資料夾
• error：發生錯誤
• ready：完成檔案／資料夾初次掃瞄，能夠開始監聽 change 事件
• raw：所有事件 (能夠取得所有事件的名稱、路徑及細節)
• all：上述所有事件 (不含 ready、raw 和 error 事件)

各個事件可提供不同的詳細資料，請參考：https://www.npmjs.com/package/chokidar

撰寫監聽任務時，要提供檔案路徑、要監聽的事件類型和任務函式。如果自行指定監聽事件，透過 {events: ...} 就能帶入。

任務函式內要傳入 callback 函式，負責通知 Gulp 這個監聽任務已完成。callback 函式是由 Gulp 自行產生，開發者不需另行宣告。

// gulpfile.js

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

function watchStyles () {
   watch('./src/css/**', {events: 'change'}, function(cb) {
       src(...)
       .pipe(...)
       .pipe(dest(...))
             
       cb()
   }) 
}

若要監聽多個事件，透過 {events: []} 以陣列帶入所有要監聽的事件：

// gulpfile.js

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

function watchStyles () {
   watch('./src/css/**', {events: ['change', 'add']}, function(cb) {
       src(...)
       .pipe(...)
       .pipe(dest(...))
             
       cb()
   }) 
}

如果任務未指定要監聽的事件，預設會監聽 add、change 和 unlink 事件。

// gulpfile.js

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

// 監聽 add、change 和 unlink 事件
function watchStyles () {
   watch('./src/css/**', function(cb) {
       src(...)
       .pipe(...)
       .pipe(dest(...))
             
       cb()
   }) 
}

更多任務設定

監聽任務函式中的第二個 argument {...} 不僅能夠帶入要監聽的事件，還能帶入更多設定，讓監聽任務更加符合需求。

以下介紹其中三種設定：ignoreInitial、queue 和 delay。

• ignoreInitial

執行監聽任務時，預設會在檔案出現變動後才會觸發任務執行。

如果希望在已經開始監聽檔案、但檔案尚未出現變動的時候就執行任務，可以傳入 {ignoreInitial: false} 設定。當監聽任務一開始執行、還未修改檔案時，就會對已有的 CSS 檔案作處理。

// gulpfile.js

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

function watchStyles () {
   watch('./src/css/*.css', {ignoreInitial: false}, function(cb) {
       src(...)
       .pipe(...)
       .pipe(dest(...))
             
       cb()
   }) 
}

• queue

由於監聽的事件可能在短時間內觸發多次 (例如快速修改檔案並存檔)，Gulp 會讓每一次觸發的任務依時間順序執行。

如果有特殊考量，希望能讓多個觸發的任務同時執行，而非依序執行，可以傳入 {queue: false} 關閉預設行為。

// gulpfile.js

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

function watchStyles () {
   watch('./src/css/**', {queue: false}, function(cb) {
       src(...)
       .pipe(...)
       .pipe(dest(...))
             
       cb()
   }) 
}

• delay

監聽函式預設會在檔案修改後 200 毫秒才執行任務，避免在一次性大量修改檔案時就執行任務，導致錯誤發生。

在特定情況下，可能需要更長的延遲時間才執行監聽任務。可以傳入 {delay: ...} 來調整延遲時間。時間單位為毫秒。

// gulpfile.js

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

// 等待 500 毫秒後再執行
function watchStyles () {
   watch('./src/css/**', {delay: 500}, function(cb) {
       src(...)
       .pipe(...)
       .pipe(dest(...))
             
       cb()
   }) 
}

如果想要了解更多監聽任務設定，參考： https://gulpjs.com/docs/en/api/watch

建立更複雜的監聽任務

先前所介紹的監聽任務都相當單純，只監聽單一檔案路徑內是否有變更；如果有變更的話，則執行一項指定任務。

然而，實際開發時所需的監聽任務可能更為複雜：必須監聽多個檔案路徑或觸發多個指定任務。

接下來會介紹這些可能的複雜情境以及如何建立合適的監聽任務。

監聽多個檔案路徑 + 執行單一任務

若要同時監聽多個檔案，在陣列內列出要監聽的所有檔案即可。

// gulpfile.js
const {watch} = require('gulp')

function informMe(cb){
    console.log('Changes detected!')
    cb()
}

// 用陣列列出所有要監聽的檔案
function watcher () {
  watch(['./src/js/**', './src/css/**'], informMe)    
}

在上面的例子中，只要 Gulp 監聽到這些資料夾內的檔案有任何變更，就會執行任務印出訊息。

監聽單一檔案路徑 + 執行多個任務

當 Gulp 監聽到單一檔案路徑內有變更，即可觸發多個任務。只需用 series 或 parallel 包住要觸發的任務。不需為個別任務撰寫對應的監聽任務，寫起來簡潔不少。

// gulpfile.js

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

function convertToJS () {...}
function uglifyJS () {...}
function concatJS () {...}

function watcher () {
  watch('./src/ts/**', series(convertToJS, uglifyJS, concatJS))    
}

在上面的例子中，當 TypeScript 檔案內發生變更，Gulp 會依序將所有的 .ts 檔案轉成 .js 檔案、進行壓縮，最後再將所有產出的 .js 檔案合併為單一 .js 檔案。

監聽多個檔案路徑 + 執行不同任務

如果必須同時監聽多個不同的檔案路徑，而且各個檔案路徑要執行的任務不相同時，還是得要為各個檔案路徑撰寫對應的監聽任務。

只是，當專案內有多個監聽任務分散四處時，在管理和執行時，可能有所遺漏，增加處理負擔。

很棒的是，可以只用一個任務函式整合多個監聽任務。如此一來，只須匯出、執行外層函式，就能同時執行多個監聽任務，維護監聽函式也更加輕鬆：

// gulpfile.js
const {watch} = require('gulp')

function watchAll () {
  watch('./src/js/**', function() {...})  
    
  watch('./src/scss/**', function() {...})
  
  watch('./src/index.html', function() {...})
}

匯出和執行監聽任務

監聽任務和一般的 Gulp 任務一樣，都必須匯出為公開任務才能執行。可以匯出為預設任務或一般任務：

// gulpfile.js

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

function watchStyles () {
   watch('./src/css/**', function(cb) {...}) 
}

function watchHTML () {
    watch('./src/index.html', function(cb) {...})
}

// 匯出為預設任務
exports.default = watchStyles
          
// 匯出為一般任務
exports.html = watchHTML

匯出監聽任務後，在終端機輸入 Gulp 指令即開始執行監聽任務。例如，輸入 gulp 或 gulp default 會執行 watchStyles 任務，輸入 gulp html 則會執行 watchHTML 任務。

用 chokidar 實例建立監聽任務 (不推薦)

以上介紹的是用 Gulp 內建的 watch 建立監聽任務的方式，也是最安全的方式。

然而，你也有機會看到類似 JavaScript 事件監聽器的其他寫法。這種寫法是利用 Gulp 內部的 chokidar 套件，直接建立 chokidar 實例來執行監聽任務：

// gulpfile.js

const {watch} = require('gulp')

// 傳入要監聽的檔案路徑，建立 chokidar 實例
const watcher = watch(['styles/sass/*.scss'])

// 註冊監聽器
// path = 受到修改的檔案的路徑
// stats = 檔案狀態 (即檔案的 metadata)
watcher.on('change', function(path, stats) {
    console.log({path, stats})
})

watcher.on('add', function (path, stats) {
    // ...
})

依據官方文件說明，建立 chokidar 實例作為監聽器會失去 Gulp 的系統優勢：

When using the chokidar instance directly, you will not have access to the task system integrations, including async completion, queueing, and delay.

容易導致錯誤發生，使得處理結果不如預期或造成效能負擔。因此已不建議使用此種寫法。

動手練習

Gulp 監聽任務最經典的使用情境是將 SCSS 即時編譯為 CSS。SCSS 語法比 CSS 更加彈性，是不少人的開發首選。但是瀏覽器無法直接讀取 SCSS，必須先執行指令將 SCSS 編譯成 CSS，瀏覽器才能讀取到樣式。

Gulp 能夠監聽 SCSS 檔案變化，就能立即產生 CSS 檔案，不需反覆手動下指令編譯，非常方便！

不過，瀏覽器並不會因為 CSS 檔案有變化而自動重新載入。在這個練習中會搭配 Browsersync 套件，依賴它來建立開發伺服器。當 HTML 或 SCSS 檔案變動時，Gulp 會通知 Browsersync 重新整理頁面，重新渲染畫面。

練習的專案資料夾結構如下：

|-- 專案資料夾/
    |-- styles/
        |-- sass/
            |-- index.scss
    |-- index.html

1. 依上述結構建立你的練習用專案。
2. 在終端機輸入下列指令進行專案初始化：

npm init -y

3. 全域安裝 gulp-cli

npm install --global gulp-cli

4. 安裝 ‘gulp’、‘sass’、‘gulp-sass’ 和 ‘browser-sync’ 套件到專案資料夾中：

npm install gulp sass gulp-sass browser-sync --save-dev

5. 在根目錄處建立 gulpfile.js 檔案。

6. 開啟 gulpfile.js 來建立任務。首先引入需要的外掛程式和套件：

// gulpfile.js

// 取出 Gulp 提供的方法
const { src, dest, parallel, watch } = require("gulp");

// 建立 browserSync 實例 (開發伺服器)
const browserSync = require("browser-sync").create();

// 引入 SASS
const sass = require("gulp-sass")(require("sass"));

7. 建立將 SCSS 轉換為 CSS 的 Gulp 任務：

// gulpfile.js

function convertSCSSToCSS() {
  return src("styles/scss/*.scss")
    .pipe(sass())
    .pipe(dest("app/styles/css"))
    .pipe(browserSync.stream());
}

這個任務將會 styles/scss 裡所有的 SCSS 檔案轉換為 CSS 檔案，並將產生的檔案放置到 app/styles/css 資料夾中。app 資料夾內也會存放所有給開發伺服器使用的資源。

最後透過 browserSync.stream() 方法回傳 stream，通知瀏覽器 CSS 檔案有變化。

8. 建立將 HTML 檔案複製到 app 資料夾的 Gulp 任務：

// gulpfile.js

function copyHTML(){
    return src('*.html')
    .pipe(dest('app'))
    .pipe(browserSync.stream())
}

一樣在最後加上 browserSync.stream() 方法回傳 stream，讓瀏覽器得知 HTML 檔案有變化。

9. 在 index.html 檔案裡要指定 CSS 檔案來源，瀏覽器才能讀取到樣式：

<!-- index.html -->

<head>
    ...
    <link rel="stylesheet" href="styles/css/index.css" />
</head>

10. 建立要匯出執行的任務：

// gulpfile.js

function serve() {
  browserSync.init({
    server: "./app",
  });

  watch(
    ["styles/scss/*.scss", "*.html"],
    { ignoreInitial: false },
    parallel(convertSCSSToCSS, copyHTML)
  );

  watch(["app/**"], browserSync.reload);
}

在這個任務中，先對 Browsersync 實例 (也就是開發用的伺服器) 進行初始化。開發伺服器的進入點設定為 ./app 資料夾。

裡面含有兩個監聽任務。第一個任務負責監聽 SCSS 檔案和 HTML 檔案是否有任何變動。如果有變動的話，依序將 SCSS 檔案轉成 CSS 檔案，再複製 HTML 檔案。產生的檔案都會放到 app 資料夾內，讓瀏覽器讀取。

監聽任務中的 {ignoreInitial: false} 設定。即使還沒修改 SCSS 檔案和 HTML 檔案，Gulp 會先產生對應的檔案到 app 資料夾。這樣一來，開啟開發網址時，就有檔案讓瀏覽器讀取。

第二個任務監聽 app 資料夾內是否有任何變動 (例如新增檔案或檔案內容有變化)。一旦發現變動，瀏覽器就會重新整理頁面，依據最新的CSS 和 HTML 內容渲染畫面。

11. 將 serve 任務匯出為公開任務，之後才能使用 Gulp 指令執行。

// gulpfile.js

function serve () {...}

exports.default = serve

12. 在終端機輸入 Gulp 指令來執行任務：

gulp

瀏覽器會自動開啟頁面 (或是點選終端機上的開發網址前往頁面)。接著就能進行開發！只要 HTML 和 SCSS 檔案有任何變化，監聽任務都會立刻執行，即時更新瀏覽器畫面。即使新增 SCSS 檔案或 HTML 檔案，Gulp 也會進行處理，讓開發伺服器和瀏覽器都能讀取到。

完整內容如下：

// gulpfile.js

const { src, dest, parallel, watch } = require("gulp");
const browserSync = require("browser-sync").create();
const sass = require("gulp-sass")(require("sass"));

function convertSCSSToCSS() {
  return src("styles/scss/*.scss")
    .pipe(sass())
    .pipe(dest("app/styles/css"))
    .pipe(browserSync.stream());
}

function copyHTML() {
  return src("*.html").pipe(dest("app")).pipe(browserSync.stream());
}

function serve() {
  browserSync.init({
    server: "./app",
  });

  watch(
    ["styles/scss/*.scss", "*.html"],
    { ignoreInitial: false },
    parallel(convertSCSSToCSS, copyHTML)
  );

  watch(["app/**"], browserSync.reload);
}

exports.default = serve;

結論

Gulp 的 watch 方法能用來建立監聽任務，自動進行處理。建立監聽任務時，除了指定監聽的檔案路徑及要執行的任務，還可以加上更多設定，讓監聽行為更加符合需求。

Gulp 監聽任務可以應付多個檔案路徑和多個執行任務，方便維護、執行監聽任務。

參考資料

• Watching Files | gulp.js
• watch() | gulp.js
• GitHub - paulmillr/chokidar: Minimal and efficient cross-platform file watching library
• Using Gulp 4 in your workflow for Sass and JS files
• [試著把切版專案升級到 gulp4.0 吧] Day31 邊開發邊看畫面變動：談 gulp.watch - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天
• Browsersync + Gulp.js
• browserSync.reload and browserSync.stream()) - what are the difference?

認識 Gulp.js 系列

想要再多瀏覽 Gulp.js 4 相關教學，別錯過下列文章！

1. 認識 Gulp.js — 你的前端開發萬用刀
2. 認識 Gulp.js — 建立 Gulp 任務
3. 認識 Gulp.js — Gulp 任務的非同步特性
4. 認識 Gulp.js — 匯出及執行 Gulp 任務
5. 認識 Gulp.js — 建立監聽任務
6. 認識 Gulp.js — 拆分 Gulp 任務

一個指令，立即執行你的 Gulp 任務！

概述

本文介紹如何匯出 Gulp 任務函式以及如何利用 Gulp/npm 指令執行任務。

本文內容如下：

．認識公開任務 vs 私有任務

．匯出預設任務 vs 匯出一般任務

．匯出基本任務 vs 匯出複合任務

．執行 Gulp 任務

認識公開任務 vs 私有任務

Gulp 任務函式皆屬於私有任務 (private task)，無法透過Gulp CLI 工具直接呼叫執行。

必須先將任務函式匯出，函式匯出後即為公開任務 (public task)，能夠進一步呼叫、執行。

未匯出的私有任務雖然無法直接呼叫執行，但是可以作為公開任務的子任務。換句話說，當公開任務裡面有私有任務，在執行公開任務時，自然就會執行內部的私有任務。

// gulpfile.js

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

// 未匯出的私有任務
// 無法直接呼叫執行
function task1 () {...}
function privateTask () {
    return src(...)
        .pipe(...)
        .pipe(dest(...))
}

// 已匯出的公開任務
// 執行公開任務時，裡面的私有任務也會執行
exports.public = series(task1, privateTask)

匯出預設任務 vs 匯出一般任務

任務可以匯出為預設任務和一般任務，差別在於採用什麼關鍵字命名：

• 預設任務：匯出時使用 default 關鍵字作為任務名稱。在同一份 gulpfile.js 內，最多只能匯出一個預設任務。
• 一般任務：匯出時用其他名稱命名的任務。在同一份 gulpfile.js 內，可以匯出多個一般任務。

// gulpfile.js

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

// 未匯出，為 private task，在 public task 內部使用
function uglifyJS () {...}
function minifyCSS () {...}
function minifyHTML () {...}
function compressPNG () {...}

// 匯出為預設任務
exports.default = parallel(uglifyJS, minifyCSS, minifyHTML, compressPNG)
                                 
// 匯出為一般任務
exports.minify = parallel(uglifyJS, minifyCSS, minifyHTML, compressPNG)

匯出基本任務 vs 匯出複合任務

在先前文章提到，src、pipe 和 desc 會回傳 stream，但 series 和 parallel 只是一般的函式，並不會回傳 stream。這樣的差異導致基本任務和複合任務的匯出方式略有不同。

基本任務可以包裝成命名函式匯出：

// gulpfile.js

// 命名函式
function myTask () {
    return src(...)
    .pipe(...)
    .pipe(dest(...))
}
exports.default = myTask

也可以用匿名函式匯出基本任務：

// gulpfile.js

// 匿名函式
exports.default = function () {
  return src(...)
    .pipe(...)
    .pipe(dest(...))
}

由 series 或 parallel 包住的複合任務，直接匯出即可，不用包在函式內再匯出：

// gulpfile.js

exports.default = parallel(task1, task2, ..., taskN)

// gulpfile.js

exports.default = series(task1, task2, ..., taskN)

若要以函式的型式匯出複合任務，寫法會稍微不同：函式內不需要加上 return 關鍵字，要另外加上 () 執行。

// gulpfile.js

function comboTask () {
    series(task1, task2, ..., taskN)()
}

exports.default = comboTaskS

執行 Gulp 任務

從 gulpfile.js 檔案中匯出的公開任務都能透過指令執行。

在 gulpfile.js 檔案中，可能會匯出多個任務。除了打開檔案確認有哪些公開任務之外，Gulp CLI 工具也提供指令，直接列出所有公開任務：

gulp --tasks

在同一份 gulpfile.js 裡的所有任務會以樹狀圖列出。在樹狀圖中，公開任務列在第一層，而內部使用的子任務/私有任務列在第二層。由此可以對任務結構有清楚掌握。

公開任務會以藍色顯示，私有任務則以白色顯示。在公開任務中，預設任務以 default 為名，其他公開任務則顯示對應的名稱。

若要執行預設任務，只須在終端機輸入 gulp 或 gulp default，就會執行該任務。

# 執行預設任務
gulp

或

# 執行預設任務
gulp default

若要執行特定名稱的任務，在終端機輸入 gulp [任務名稱]，就會執行對應的任務。例如要執行名稱為 minify 的任務：

# 執行一般任務
gulp minify

經常執行的 Gulp 指令可以寫在 npm package.json 的 scripts 內，作為 npm 指令使用。當 Gulp 指令變複雜時，只需輸入簡短的 npm 指令就能順利執行、避免出錯。

例如在 package.json 裡建立了兩個 npm 指令：

// package.json

"scripts": {
    "build": "gulp",
    "minify": "gulp minify"
}

在終端機輸入 npm run build 和 npm run minify 就會執行對應的 Gulp 任務。

結論

gulpfile.js 內的任務函式皆是私有任務；私有任務必須匯出成為公開任務後，才能透過 Gulp/npm 指令執行。

參考資料

Creating Tasks | gulp.js

認識 Gulp.js 系列

想要再多瀏覽 Gulp.js 4 相關教學，別錯過下列文章！

1. 認識 Gulp.js — 你的前端開發萬用刀
2. 認識 Gulp.js — 建立 Gulp 任務
3. 認識 Gulp.js — Gulp 任務的非同步特性
4. 認識 Gulp.js — 匯出及執行 Gulp 任務
5. 認識 Gulp.js — 建立監聽任務
6. 認識 Gulp.js — 拆分 Gulp 任務

概述

本文會介紹為何需要在 Gulp 任務中加入非同步完成的標示以及加入標示的方法。

同時透過實際經驗推敲出，基本任務和複合任務在加入非同步完成標示時有些許不同。

本文內容如下：

．什麼是非同步完成 (async completion)

．如何標示非同步任務已完成

．To return a stream or not to?

什麼是非同步完成 (async completion)？

在 Gulp 4 中，所有的 Gulp 任務皆是非同步任務。由於非同步特性，我們無法確切掌握某個任務是否已經執行完畢、是否能夠接著執行下一個相依任務。這樣一來，一連串任務執行下來，過程中可能發生錯誤或結果不如預期。

因此，Gulp 4 另外提供多種方式用來標示非同步的任務已完成 (async completion)：當 Gulp 接收到標示後，就會安心進行下一個非同步任務。

如果忘了在任務中加上非同步完成的標示，Gulp 一樣會執行任務，只是執行結果變得無法掌握。

Gulp 也會在 terminal 中拋出警告訊息 “Did you forget to signal async completion?”，提醒開發者應加上非同步完成的標示。

如何標示非同步任務已完成

根據官方文件，有 7 種方式可以標示任務已完成：

• 回傳 Node.js stream、event emitter 或 child process
• 回傳 Rx.js 的 observable
• 回傳 Promise
• 傳入錯誤優先處理函式 (error-first callback)

以下介紹常見的方式：回傳 Node.js stream (推薦)、回傳 Promise 和傳入錯誤優先處理函式。

回傳 stream

在開頭加上 return 即可。

// gulpfile.js

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

function task () {
    return src(...)
        .pipe(...)
        .pipe(dest(...))
}

從 src 開始到 dest 結束，檔案資料都以 stream 格式傳遞和接受處理。因此，只要加上 return 就能回傳 stream。

Gulp 用到的外掛程式通常是對 stream 做處理，處理完後也會回傳 stream。因此，在任務函式中回傳 stream 來標示非同步完成，基本上都不會有問題。

回傳 Promise

// gulpfile.js

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

function task () {
    return Promise.resolve(
      src(...)
      .pipe(...)
      .pipe(desc(...))
    )
}

使用錯誤優先處理函式 (error-first callback)

如果不回傳上述類型的資料，必須提供錯誤優先處理函式作為任務函式的 argument。

錯誤優先處理函式通常以 cb 代表 (即 callback 縮寫)。cb() 內可不傳入任何值，也可以放入 console.log 印出提示。

// gulpfile.js

function task (cb) {
    src(...)
     .pipe(...)
     .pipe(dest(...))
         
    // 通知 Gulp 非同步任務已完成     
    cb() 
    
    // 通知 Gulp 非同步任務已完成 + 印出 console 提示
    cb(console.log("Task done"))
}

不過，開發者不需要自行宣告錯誤優先函式。根據這一篇 StackOverflow，這個 callback 是由 Gulp 4 引用的 undertaker 套件提供：

The callback function comes from Orchestrator (or the new one — undertaker — in Gulp 4) and is actually nothing more than a call to tell the task system that your task is “done”.

什麼時候適合用到錯誤優先處理函式呢？根據同一篇 StackOverflow 的回答，如果該任務用到的外掛程式不會回傳 stream，適合傳入 callback。

By returning a stream, the task system is able to plan the execution of those streams. But sometimes, especially when you’re in callback hell or calling some streamless plugin, you aren’t able to return a stream. That’s what the callback is for. To let the task system know that you’re finished and to move on to the next call in the execution chain.

To return a stream or not to?

雖然知道如何在 Gulp 中標示非同步任務完成，也儘量使用回傳 stream 的方式，但在實際使用上還是不免碰到不少疑問：

• 以上方式都可以任意使用嗎?
• 某些任務只適合某些方式嗎?
• 為什麼回傳了 stream，還是出現 “Did you forget to signal async completion?” 警告訊息或任務沒有成功執行?

自己摸索一番後推敲出基本任務和複合任務的非同步完成標示方式不太相同。

關鍵在於 series 和 parallel 和 src 還有 dest 都是函式，但有不同的回傳值。

基本任務

src 和 dest (包含 pipe) 都和 Node.js stream 有關，負責回傳 stream。用 console.log可以看到 stream 物件有極複雜的內容。

// gulpfile.js

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

// 印出複雜的 stream 物件
console.log(src(...))
console.log(src(...).pipe(...))
console.log(src(...).pipe(...).pipe(dest(...)))

因此，要標示非同步的基本任務完成，可以回傳 stream，也可以用其他的方式：

// gulpfile.js

// OK
function task () {
    return src(...)
    .pipe(...)
    .pipe(dest(...))
}

// OK
function task () {
    return Promise.resolve(
      src(...)
      .pipe(...)
      .pipe(dest(...))
    )
}
        
// OK
function task (cb) {
  src(...)
  .pipe(...)
  .pipe(dest(...))
          
  cb()
}

複合任務

series 和 parallel 是負責為任務建立排程的函式，執行後回傳 undefined 而非 stream。透過 console.log 印出函式則更容易了解：

// gulpfile.js

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

function task1 () {...}
function task2 () {...}

// [Function: series] [Function: parallel]
// 函式已宣告但未執行
console.log(series(task1, task2), parallel(task1, task2))
                   
// undefined undefined
// 函式已執行
console.log(series(task1, task2)(), parallel(task1, task2)())

從印出的資料中可以看出，series 和 parallel 行為就像是一般沒有回傳值的 JavaScript 函式。

由於複合任務執行後不會回傳 stream，用回傳 stream 的方式標示則會出現警告訊息。用錯誤優先函式和 Promise 處理則會更適合。

// gulpfile.js

// BAD 
// 任務沒有執行，出現警告訊息；只是回傳函式，但沒有執行
function task() {
    return series(...)
}

// KINDA BAD 
// 任務成功執行，出現警告訊息
function task () {
    return series(...)()
}               

// OK
function task() {
    return Promise.resolve(
      series(...)()
    )
}

// OK
function task (cb) {
    series(...)()
    cb()
}

要注意的是，必須在 series 和 parallel 函式後加上 ()，才會執行裡面的基本任務。

結論

總結來說，基本任務可以用各種方式通知 Gulp 非同步任務已完成。

複合任務則無法使用回傳 stream 的方式。因為複合任務只是一般的函式，不會回傳 stream，因此不適合用回傳 stream 的方式標示。

參考資料

• Async Completion | gulp.js
• Chapter 2. Getting started with Gulp · Front-End Tooling with Gulp, Bower, and Yeoman

https://stackoverflow.com/questions/29298244/gulp-where-is-the-gulp-task-callback-function-defined#:~:text=The callback function comes from,your task is “done”

認識 Gulp.js 系列

想要再多瀏覽 Gulp.js 4 相關教學，別錯過下列文章！

1. 認識 Gulp.js — 你的前端開發萬用刀
2. 認識 Gulp.js — 建立 Gulp 任務
3. 認識 Gulp.js — Gulp 任務的非同步特性
4. 認識 Gulp.js — 匯出及執行 Gulp 任務
5. 認識 Gulp.js — 建立監聽任務
6. 認識 Gulp.js — 拆分 Gulp 任務

認識 src、pipe、dest、series 和 parallel 方法

概述

本文會深入介紹 Gulp 任務中的重要方法：src、pipe、dest、series、parallel。

這些方法可以用來建立 Gulp 基本任務，或是將基本任務串連起來組成複合任務。

Gulp 官方文件並沒有區別基本任務和複合任務。由於兩者的寫法和一些特性差異，在本文中會介紹這兩種任務：

• 基本任務：由 src、pipe 和 dest 組成的任務，對應到一則 JavaScript 函式。
• 複合任務：由 series 或 parallel 組裝多個基本任務而成的複雜任務。

認識基本任務

Gulp 基本任務是由 src、pipe 和 dest 組成的任務，對應到一則 JavaScript 函式。

了解如何使用 src、pipe 和 dest 可以讓我們更清楚如何撰寫 Gulp 任務。

src()：用 glob 格式指定檔案來源

src() 用來指定要處理的檔案或資料夾路徑。

指定路徑時，要使用 glob 格式。glob 是一種用來表示檔案路徑的格式，可以寫出明確的檔案路徑或搭配特殊符號一次指定多個檔案。

如果來源為明確的單個檔案，在 src() 裡提供檔案路徑字串；如果是好幾個明確的檔案，用陣列標明所有檔案的路徑。

// gulpfile.js

// 來源為單一檔案
function singleFileTask () {
 return src('css/style.css')
 .pipe(…)
 .pipe(dest(…))
}

// 來源為多個檔案
function multiFilesTask () {
 return src(['css/style.css', 'css/mobile.css'])
 .pipe(…)
 .pipe(dest(…))
}

要注意的是，要提供相對於 gulpfile.js 的檔案路徑。

glob 格式也可以搭配特殊字元使用，能夠一次指定多個符合條件的檔案。

常見的 glob 特殊字元：

• *：0 到多個任意字元
• **：0 到多層的資料夾
• ?：1 個任意字元，不區分大小寫
• !：否定字元，排除指定的檔案和資料夾

一起來了解這些特殊字元的用法：

// gulpfile.js

// 'styles' 資料夾內 (第一層) 所有 CSS 檔案
src('styles/*.css')

// 'js' 資料夾內 (不論內部有多少層資料夾) 的所有 index.js 檔案
// ('js/index.js'、'js/core/index.js'、'js/core/apis/index.js' 等等)
src('js/**/index.js')

// 'img' 資料夾內 (不論內部有多少層資料夾) 的所有 PNG 檔案
// ('img/brand.png'、'img/icon/add.png'、'img/pages/banners/sale.png' 等等)
src('img/**/*.png')

// 'img' 資料夾內 (第一層), 所有名稱為任何字元 + ig 的 PNG 檔案 
// (例如：big.png, dig.png, Pig.png, Fig.png)
src('img/?ig.png')

// 'app' 資料夾裡所有的 js 檔案，但是不包含 'node_modules' 資料夾
// 換句話說，'node_modules' 內任何 js 檔案皆略過不處理
// 必須先列出要處理的項目，最後才列出不要的項目 (也就是帶有 ! 的項目)
src(['app/**/*.js', '!node_modules/**'])

要注意的是，使用 ! 時，src() 中的檔案路徑要用陣列標示：先舉出要處理的檔案路徑，最後才舉出要排除的檔案路徑 (也就是加上 ! 的路徑)。

除了上述介紹的特殊字元外，glob 另有其他的特殊字元可以搭配使用。然而，對於一般專案來說，只要檔案放置得宜，* 和 ** 已可滿足大多數需求。

src() 找到指定檔案後，會將這些檔案轉換為 Node.js stream，再轉給接下來的 pipe() 處理。

pipe()：結合外掛程式進行處理

pipe 是 Node.js stream 的內建方法。一個 pipe() 會搭配一個外掛程式，相等於一個處理步驟，也是 Gulp 任務中最重要的部份。

取得 src() 提供的 Node.js stream 後，pipe() 會依照外掛程式的功能進行處理。使用外掛程式時，可能要額外提供一些設定值 (參考外掛程式說明文件)。

pipe() 處理完後，會再回傳 stream 給下一個 pipe() 接力處理。串接多個 pipe() 即可將多個步驟串連成一組工作流程。

dest()：輸出檔案到指定目的地

dest() 負責將上一個 pipe() 處理完的資料輸出到目的地。

dest() 要放在 pipe() 中使用，負責將上一個 pipe() 傳來的 stream 以檔案格式輸出到指定的位置。輸出路徑用字串標示。

試寫第一個基本任務

有了前面介紹的 src、pipe 和 dest 概念後，就可以來模擬撰寫第一個基本任務。

任務需求：

• 壓縮所有 HTML 檔案，同時去除裡面不必要的空格。
• 壓縮後的 HTML 檔案輸出到 dist 資料夾。

能夠壓縮 HTML 檔案的外掛程式眾多，在這裡以 gulp-htmlmin 作為外掛程式。

// gulpfile.js

// 匯入 Gulp 方法和外掛程式
const { dest, src } = require("gulp");
const htmlmin = require("gulp-htmlmin");

// 建立任務函式
function minifyHTML() {
 // 來源指定為專案資料夾內所有 HTML 檔案
 return src("./**/*.html")
 // 使用外掛程式進行壓縮，加上壓縮空白字元功能
 .pipe(htmlmin({collapseWhitespace: true }))
 // 輸出檔案至 'dist' 資料夾
 .pipe(dest("dist"));
}

認識複合任務

了解如何建立基本任務後，一起來了解如何將多個基本任務組裝成複合任務。

Gulp 提供 series 和 parallel 方法，可將多個任務組合成複合任務，控制基本任務的執行順序：

• series(task1, task2, ..., taskN)：依序從 task1 執行到 taskN。適合用在基本任務有相依性/特定執行順序時使用，確保處理結果正確。
• parallel(task1, task2, ..., taskN)：同時執行所有任務。適合當基本任務彼此獨立時使用，能夠縮短整體處理時間。

用 series 和 parallel 組合基本任務就能建立複合任務。series() 和 parallel() 也可以作為彼此的子任務：

// gulpfile.js

// 匯入 Gulp 方法和外掛程式
const { dest, src, series, parallel } = require("gulp");
const plugin1 = require("plugin1");
const plugin2 = require("plugin2");
const plugin3 = require("plugin3");
const plugin4 = require("plugin4");

// 建立基本任務
function task1 () {…}
function task2 () {…}
function task3 () {…}
function task4 () {…}

// 複合任務：依序從 task1 執行到 task4
series(task1, task2, task3, task4)
 
// 複合任務：同時執行四個任務 
parallel(task1, task2, task3, task4)
 
// 複合任務：執行 task1，接著執行 parallel(task2, task3), 最後執行 task4
series(task1, parallel(task2, task3), task4)
 
// 複合任務：同時執行 task1、series(task2, task3) 和 task4
parallel(task1, series(task2, task3),task4)

// 其他可能任務組合…

不要重複執行任務

使用 series 和 parallel 組裝基本任務時，記得避免重複執行特定任務，以免發生錯誤或拉長處理時間。

設計不良的複合任務 (取自 Gulp 官網範例)：

// gulpfile.js

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

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

const css = series(clean, function(cb) {
 // body omitted
 cb();
});

const javascript = series(clean, function(cb) {
 // body omitted
 cb();
});

exports.build = parallel(css, javascript);

在上述範例中，css 和 javascript 複合任務都會執行clean 基本任務。也就是，clean 任務會執行兩次。

由於 clean 任務執行一次後就會清除目標檔案，再執行一次 clean 任務並沒有意義。另外，執行第二次 clean 任務時，指定的目標檔案已不存在，找不到要處理的檔案可能導致錯誤發生。

設計較佳的任務 (取自 Gulp 官網範例)：

// gulpfile.js

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

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

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

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

exports.build = series(clean, parallel(css, javascript));

比較好的作法是將重覆用到的 clean 任務抽取出來。執行一次 clean 任務後，再同時執行 css 和 javascript 任務。如此一來，執行結果能夠滿足需求，不會重覆執行導致錯誤發生。

試寫第一個複合任務

有了前面介紹的 series 和 parallel 概念後，就可以來模擬撰寫第一個複合任務。

任務需求：

• 將 Markdown 檔案轉換成 HTML 檔案。
• 壓縮 HTML 檔案，同時去除裡面不必要的空格。
• 壓縮後的 HTML 檔案輸出到 dist 資料夾。

在這裡會使用的外掛程式：

• gulp-remarkable：將 Markdown 轉換成 HTML。
• gulp-htmlmin：壓縮 HTML 內容。

// gulpfile.js

// 匯入 Gulp 方法和外掛程式
const { dest, src, series } = require("gulp");
const markdown = require("gulp-remarkable");
const htmlmin = require("gulp-htmlmin");

function convertMarkdownToHTML() {
 return src('readme.md')
 .pipe(markdown())
 .pipe(dest('dist'))
}

function minifyHTML() {
 return src("dist/readme.html")
 .pipe(htmlmin({collapseWhitespace: true }))
 .pipe(dest("dist"));
}

exports.build = series(convertMarkdownToHTML, minifyHTML)

從流程順序思考，必須先將 Markdown 轉換成 HTML 後才能進行壓縮，代表任務之間有相依性，因此使用 series 方法安排任務。

convertMarkdownToHTML 任務會將 Markdown 轉換成 HTML，輸出 HTML (readme.html) 至 dist 資料夾。minifyHTML 任務接著處理 readme.html，再將結果輸出至 dist 資料夾。由於輸出檔案與原有檔案同名，會自動覆蓋之前的檔案。

結論

Gulp 基本任務由 src、pipe 和 dest 組成，對應到一則 JavaScript 函式。在 src 內要用 glob 格式指定來源檔案；在 pipe 內指定外掛程式；在 dest 內指定檔案輸出位置。

Gulp 複合任務由 series 或 parallel 組裝多個基本任務而成。series 能讓任務依序執行，parallel 能讓任務同時執行。要注意是否有任務重覆執行，以免拉長處理時間或發生錯誤。

參考資料

https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns

• Gulp 學習筆記 - Glob 篇
• Understanding the glob pattern in Node.js - LogRocket Blog
• Explaining Globs | gulp.js
• Creating Tasks | gulp.js

認識 Gulp.js 系列

想要再多瀏覽 Gulp.js 4 相關教學，別錯過下列文章！

1. 認識 Gulp.js — 你的前端開發萬用刀
2. 認識 Gulp.js — 建立 Gulp 任務
3. 認識 Gulp.js — Gulp 任務的非同步特性
4. 認識 Gulp.js — 匯出及執行 Gulp 任務
5. 認識 Gulp.js — 建立監聽任務
6. 認識 Gulp.js — 拆分 Gulp 任務

認識 Gulp.js 及整體處理流程

概述

本文會介紹 Gulp.js 的用途及大致運作流程。

本文內容如下：

．什麼是 Gulp.js?

．Gulp.js 核心 — 外掛程式 (plugin)

．Gulp 任務

．用 JavaScript 實現 Gulp 任務

什麼是 Gulp.js？

Gulp 是自動化流程處理工具，可與各種外掛程式結合，執行不同任務。開發者透過 JavaScript 就能撰寫處理任務，組合成一套符合自己需求的工作流程。

透過 CLI 指令即可自動執行一連串繁瑣、重複性高的工作流程，大幅提升開發效率。

Gulp.js 核心 — 外掛程式 (plugin)

Gulp 運作基礎在於豐富多樣的外掛程式 (plugin) 生態系：每個外掛程式各自負責單一功能，能夠讀取、修改、寫入檔案。

常見的外掛程式功能有修改檔名、壓縮檔案內容及合併檔案內容等等。

開發者除了能依需求下載適合的外掛程式來使用，還可以串連多個外掛程式組裝成不同的處理流程，滿足各種開發情境需求。

搜尋 Gulp 外掛程式的網站：

• 官方網站：https://gulpjs.com/plugins
• npm Registry：https://www.npmjs.com (加上 「gulp」 關鍵字)

Gulp 任務

Gulp 任務是工作流程的核心元素，由三個基礎方法構成：

• src()：指定輸入的來源檔案／資料夾。
• pipe()：指定要使用的外掛程式。一個 pipe() 等於一個處理步驟，每個處理步驟由外掛程式負責。
• dest()：指定資料輸出的目的地。dest() 要放在 pipe() 內使用。

Gulp 從 src() 輸入要處理的檔案，經過各個 pipe() 及外掛程式的處理，再將最終成果輸出到 dest() 指定的位置：

src(來源) 
> pipe(外掛1) 
> …
> pipe(外掛N) 
> pipe(dest(目的地))

假設有一個任務要將 SCSS 轉換為 CSS 檔案，CSS 檔案內容也要壓縮：

src(style.scss) 
> pipe(轉換為 CSS) 
> pipe(壓縮 CSS) 
> pipe(dest(style.css))

不論需求如何改變，Gulp 任務都有類似的架構。

用 JavaScript 實現 Gulp 任務

在 Gulp 中實現上述流程的方式是用 JavaScript 撰寫任務。一個任務對應到一則 JavaScript 函式。

在任務內可以任意串連多個 pipe()，讓不同外掛程式接力處理資料。

要注意的是，Gulp 任務函式必須寫在 gulpfile.js 檔案內，Gulp 才能讀取到裡面的函式來執行任務。

任務的基本寫法：
1. 引入要使用的 Gulp 方法和外掛程式。
2. 建立任務函式。函式內含 src()、pipe() 和 dest()。

// gulpfile.js

// 引入 Gulp 方法及外掛程式
const {src, dest} = require('gulp')
const plugin1 = require('plugin1')
const plugin2 = require('plugin2')

// 函式即任務
function 任務 () {
  return gulp.src('來源路徑')
   .pipe(plugin1())
   .pipe(plugin2())
   .pipe(dest('目的地路徑'))
}

結論

Gulp.js 能建立符合自動化處理流程。整體運作流程以任務為核心。透過 JavaScript 即可自行撰寫任務，在任務內指定檔案來源、用到的外掛程式和資料輸出位置，輕鬆建立符合需求的處理流程。

下一篇文章會深入 src()、pipe() 和 dest() 的用法。

參考資料

• Quick Start | gulp.js
• Chapter 2. Getting started with Gulp · Front-End Tooling with Gulp, Bower, and Yeoman

認識 Gulp.js 系列

想要再多瀏覽 Gulp.js 4 相關教學，別錯過下列文章！

1. 認識 Gulp.js — 你的前端開發萬用刀
2. 認識 Gulp.js — 建立 Gulp 任務
3. 認識 Gulp.js — Gulp 任務的非同步特性
4. 認識 Gulp.js — 匯出及執行 Gulp 任務
5. 認識 Gulp.js — 建立監聽任務
6. 認識 Gulp.js — 拆分 Gulp 任務

概述

輸入欄位、進度條、核取方塊 (checkbox)、單選按鈕 (radio button) 等表單控制項目 (form controls) 樣式由瀏覽器控制，無法直接用一般的 CSS 選擇器進行處理。如果自行手刻表單元件，需要處理 HTML、CSS 和 JavaScript 三者互動，會耗費不少時間。

幸運的是，CSS 內有一些屬性和偽元素能夠解開瀏覽器的封印，讓我們調整元件的樣式。一起來認識這些屬性和選擇器吧！

對照 CodePen 看會更有感覺 (建議使用 Chrome 最新版開啟)。

本文內容如下：

• 用 accent-color 調整重點顏色
• 用 appearance: none 和偽元素 (pseudo-element) 大幅度重設樣式
• 核取方塊 (<input type="checkbox">)
• 單選按鈕 (<input type="radio"/>)
• 檔案上傳按鈕 (<input type="file">)
• 滑桿 (<input type="range">)
• 進度條 (<progress>)
• 計量條 (<meter>)
• 一般輸入框 (<input>)
• 數字輸入框 (<input type="number">)
• 搜尋輸入框 (<input type="search">)

用 accent-color 調整重點顏色

強調色 (accent color) 是指頁面主要顏色 (primary color) 的對比色，在頁面上的視覺效果突出，能夠吸引引使用者的注意。

在各家瀏覽器中，表單項目的預設強調色為藍色。如果要改用其他顏色，用 accent-color 就能進行設定。

<label><input type="checkbox">Checkbox</label>
<label><input type="radio">Radio button</label>
<label><input type="range">Range slider</label>
<progress value="0.5"></progress>

接著再勾選所有選項，就會發現套用新的顏色了。

同時，也會發現進度條中不僅代表值的部份改變顏色，連空白部份的顏色也改變了。這是瀏覽器自動計算的結果，確保進度條的值和空白有足夠的視覺對比。

目前 accent-color 只能用在下列 HTML 元素：

• <input type="checkbox">
• <input type="radio">
• <input type="range">
• <progress>

用 appearance: none 和偽元素 (pseudo-element) 大幅度重設樣式

appearance: none 會取消瀏覽器對表單項目的樣式設定，允許我們自行設計表單項目的外觀。在這裡會搭配 -webkit 偽元素或一般偽元素來處理細部樣式。

appearance: none 可相容大部份的新版瀏覽器。若要相容較舊的瀏覽器，可加入帶有 vendor prefix 的屬性：

• Safari、Chrome、iOS 和 Android：-webkit-appearance: none
• Firefox：-moz-appearance: none

使用 vendor prefix 屬性時，記得要放在標準屬性之前。

如果瀏覽器只能理解 vendor prefix 屬性，會自動忽略不支援的標準屬性。

如果瀏覽器皆能理解這些屬性，則會依順序採用標準屬性，避開行為不穩定的 vendor prefix 屬性，因為各家瀏覽器推出的 vendor prefix 屬性實作效果可能不一致。

順帶一提，appearance: none 會取消原有樣式，之前介紹的 accent-color 設定會連帶失效。

以下會示範如何調整核取方塊、單選按鈕、數字輸入框、滑桿和進度條的樣式。

核取方塊 (<input type="checkbox">)

核取方塊不需要選取特別的偽元素來修改細部樣式。

只有在修改勾選符號樣式時，才會用到 ::before 或 ::after 這些常見的偽元素。這些偽元素裡會用到 content 屬性。

content 屬性可以接受不同的值：

• 字串 (一般文字或 CSS code)
• 圖片路徑
• 線性漸層 (linear gradient)、放射漸層 (radial gradient)、錐狀漸層 (conic-gradient) 等各種漸層

<input type="checkbox">

偽元素裡的 content 屬性可直接寫入要呈現的字串或特殊符號的 CSS code。

content 屬性可以接受圖片路徑，但無法控制圖片大小。可以搭配 transform 屬性調整圖片大小和位置。

另一種比較推薦的作法是：content 不設定任何值，只設定偽元素的寬、高。用 background-image 將圖片置入偽元素中，再利用 background-size 控制背景圖片大小。

content 也可以設定漸層色。設定好偽元素的寬、高後，就可以呈現漸層色塊。

單選按鈕 (<input type="radio"/>)

單選按鈕也是利用 ::before 或 ::after 偽元素，搭配 content 屬性處理。如同在處理核取方塊時一樣，利用 content 屬性可呈現圖片、漸層色，能讓勾選符號看起來更有創意。

<input type="radio"/>

檔案上傳按鈕 (<input type="file">)

檔案上傳按鈕的樣式可由 ::file-selector-button 偽元素進行調整。文字內容由瀏覽器決定，僅能修改文字樣式。

<input type="file">

滑桿 (<input type="range">)

::-webkit-slider-thumb 和 ::-webkit-slider-runnable-track 可以分別選取到滑桿把手和滑桿軌道。

要注意的是，修改滑桿軌道的樣式不須加入 appearance:none，但修改滑桿把手時必須加入 appearance:none。

<input type="range">

進度條 (<progress>)

透過::-webkit-progress-value 能夠修改進度值的樣式，::-webkit-progress-bar 可修改整體進度條的樣式。

<progress value="0.5">50%</progress>

計量條 (<meter>)

::-webkit-meter-inner-element 可以修改計量條外框的樣式，::-webkit-meter-bar 可以修改計量條整體樣式。

<meter min="0" low="30" optimum="70" high="80" max="100" value=""></meter>

在一般情況下，無法修改內部累計值條的樣式。只有當累計值達到特定範圍時，才可顯示對應的樣式。

::-webkit-meter-optimum-value：當 value 與 optimum 值一致時，則會顯示指定樣式。

::-webkit-meter-suboptimum-value：當 value 值比 low 值低或比 high 值高，會顯示指定樣式。用來表示值落在非預期的範圍外。

::-webkit-meter-even-less-good-value：當 value 和 optimum 值皆不位於 low 至 high 中間範圍，而且分別落在兩端。用來差示目前數值與理想值不僅落在預期範圍外，而且兩者差距過大，為相當不理想的狀況。屬性值符合下列狀況時，會顯示指定樣式：

• value < low < high < optimum
• optimum < low < high < value

一般輸入框 (<input>)

輸入框的 placeholder 屬性用來提示使用者應輸入什麼資料或資料格式。預設為淺灰色。透過 ::placeholder 偽元素可修改文字樣式。

<input placeholder="Enter name">

數字輸入框 (<input type="number">)

::-webkit-inner-spin-button 偽元素選取到數字輸入框內預設的上下箭頭按鈕 (用來增加或減少框內的數字)。這個偽元素比較特別，不用 appearance: none，就可以修改部份樣式。

例如，可以用 display: none 移除預設箭頭按鈕。輸入框能夠輸入更多位數的數字。即使移除箭頭按鈕，仍然可以利用鍵盤上下箭頭鍵來調整數值。

<input type="number">

大部份的 CSS 屬性無法調整箭頭按鈕的樣式，transform 是少數有作用的屬性：

如果加上 appearance: none，可以修改多一點的樣式，但箭號會消失不見。也無法更換箭號或設定其他實用的樣式。

搜尋輸入框 (<input type="search">)

在搜尋輸入框內輸入內容時，會出現瀏覽器預設的清除輸入內容按鈕，讓使用者可以一次清除輸入的內容。透過 ::-webkit-search-cancel-button 可以移除這個按鈕，避免使用者手誤清除已輸入的內容。

<input type="search">

結論

表單控制項的樣式大多受到瀏覽器控制，無法直接修改。透過 accent-color、appearance: none 和偽元素，開發者能有更大自由修改樣式。特別是 -webkit- 開頭的偽元素，能夠讓我們進入元件內部，直接修改細部樣式。

透過上面介紹的方法，開發者不需特別費心自製符合需求的表單元件。只需稍微修改樣式，不需重寫原有功能，開發效率更好。也不需引入任何 UI 庫或函式庫，能夠減少專案程式碼大小。

如果想要修改其他沒有介紹到的表單元件，但發現無法透過一般 CSS 語法直接調整，建議先使用 appearance: none 試著解開瀏覽器的樣式封印，再查查看有無對應的偽元素能夠達成需求。

若無法達成需求，再考慮自製需要的元件或引入合適的 UI 庫/函式庫來處理。

參考資料

• Styling Cross-Browser Compatible Range Inputs with CSS
• Pure CSS Custom Styled Radio Buttons
• Pure CSS Custom Checkbox Style
• accent-color
• WebKit CSS extensions
• 12 CSS3 Vendor Prefix Crisis Myths
• CSS Vendor Prefixes
• 網頁設計色彩配置概念

概述

GitLab 採用雙因素驗證 (two-factor authentication，2FA)，與傳統的單一因素密碼驗證相比，能夠提高資料安全性。

GitLab 雙因素驗證需要搭配 personal access token (PAT)。啟動雙因素驗證後，需使用 PAT 作為個人專屬的驗證碼。

將 PAT 儲存在電腦上後，不需要再次輸入帳號密碼，就能直接存取 GitLab 儲存庫，相當方便。

本文會引導 GitLab 使用者完成下列設定：

1. 在 GitLab 啟動雙因素驗證
2. 建立 GitLab PAT
3. 將 PAT 紀錄到電腦上

啟動雙因素驗證

GitLab 雙因素驗證要求使用者提供兩種驗證因素進行驗證：

• Personal Access Token (PAT，作用類似密碼)
• 行動裝置

與以往只需密碼即可登入的流程相比，雙因素驗證更能提高資料安全性。

1. 先在行動裝置上安裝用來產生一次性密碼的驗證程式。GitLab 推薦使用 Authy、Duo Mobile、Google Authenticator 和 Microsoft Authenticator。此處以 Google Authenticator 為例。
2. 使用個人帳號、密碼登入 GitLab。
3. 按一下左方側欄上的 Account 類別。
4. 按一下 Enable Two-factor Authentication。畫面中會出現 QR code 及相關資料。
5. 開啟行動裝置上的驗證程式，採用任一方式來產生一次性密碼：

• 掃瞄 QR code (推薦)
• 依照驗證程式說明，手動輸入 GitLab QR code 旁列出的 Account 及 Key 字串

6. 成功後，驗證程式中會出現六碼數字的一次性密碼。將一次性密碼輸入到 GitLab 頁面 QR code 下方的 Pin code 欄位。

7. 按一下 Submit。

8. 成功完成二因素驗證後，GitLab 會提供一份 recovery codes，內有多個一次性密碼。按一下 Download codes 下載 recovery codes (檔名為 gitlab-recovery-codes.txt)，再將檔案保存在安全的地方。如果日後遺失行動裝置，可以使用檔案內的一次性密碼登入 GitLab。

建立 PAT

成功啟動雙因素驗證後，接著建立 PAT。

1. 在 GitLab 頁面上，按一下右上方的大頭貼。
2. 按一下選單中的 Edit profile。
3. 按一下左側導覽列的 Access Tokens。
4. 前往 Personal Access Tokens 區塊，填入所需資料：

• Toke name：用來辨識該 PAT 的名稱。建議用 PAT 的用途來命名。
• Expiration date：指定該 PAT 到期日。
• Select scopes：選取該 PAT 適用的權限層級。建議全部勾選。

5. 按一下 Create personal access token 來建立 PAT。複製 PAT 後，再存放在安全的地方。

6. 建立好的 PAT 會出現在 Active personal access tokens 區塊內。如果要取消已建立的 PAT，按一下 Revoke，該 PAT 立即失效。

再次登入

建立 PAT 後，原有的密碼即失效，因此要重新登入 GitLab。使用 PAT 作為新的密碼來重新驗證。

1. 登出您的 GitLab 帳號，回到登入頁面。
2. 填入您的帳號，密碼則填入剛才複製的 PAT。即可進入 GitLab 主畫面。
   由於先前已啟動二因素驗證，之前手動設定的密碼會失效，只可使用 PAT 作為密碼登入。

在本機電腦儲存 PAT

將 PAT 儲存在常用的工作電腦中，就不用重覆手動輸入。之後進入 GitLab 專案，電腦就會自動取用 PAT 登入，不用再手動輸入密碼。

這裡會以 macOS 的鑰匙圈存取 (Keychain Access) 程式做示範。鑰匙圈存取是 macOS 專門用來管理使用者眾多服務帳號密碼的應用程式。

1. 開啟 macOS 的 鑰匙圈存取應用程式。
2. 在上方工作列中按一下 檔案 > 新增密碼項目。
3. 填入下列資料：

• 鑰匙圈項目名稱：填入 GitLab 專案網址 (例如https://example.git.com)。
• 帳號名稱：填入你的 GitLab 登入帳號。
• 密碼：填入你的 PAT。

4. 按一下 加入 即完成。

在此臺電腦上即可自動登入 GitLab 專案，不用再手動輸入帳號密碼。只有在 PAT 到期時，才需要再建立新的 PAT，並在鑰匙圈存取應用程式中更新密碼。

結論

和傳統常見的密碼驗證流程相比，雙因素驗證步驟較為繁瑣，但提供了更安全的登入機制，減少惡意使用者取得重要資料的可能性。

搭配 PAT 使用，還能讓登入流程更加簡化，不再需要手動輸入帳號密碼，減少帳密流出的風險。

參考資料

• Enforce two-factor authentication
• Two-factor authentication
• Personal access tokens
• 什麼是雙因素驗證 (2FA)？