# gulp 安裝與除錯紀錄：npm install 卡住 + git push卡住 + gulp deploy 錯誤
###### tags: `Git`, `GitHub`,`環境設定`
> 這次是使用六角學院 gulp 環境安裝教學 : https://hackmd.io/yWpLNMPRT2yvIR4Zq_idGw?view
## 電腦環境
iMac 24 inch M1晶片 2021。macOS Monterey 版本 12.6。
## 預先步驟
依照六角的教學文章，已經事先做好的步驟有：
- [Git 官網](https://git-scm.com/) 下載好 Git 並安裝好。
- 安裝好 node ，用 `node -v` 檢查版本是 v14.19.3 ；
- 在終端機輸入 `sudo npm i gulp@4 -g` 安裝好 gulp
(mac 使用者一定要加上 sudo 不然會出現權限阻擋的報錯)，用 `gulp -v` 檢查版本是
```
CLI version: 2.3.0
Local version: 4.0.2
```
- 下載好六角教學文章步驟三的「gulp 環境指定資料夾」，解壓縮後，放在電腦內的任意合適位置。
- 開啟終端機 `cd` 移動進入這個指定資料夾。( 可以透過 `ls` 指令檢查資料夾內的檔案，確認是來到目的地。)
```
cd /Users/judy/Documents/Hex-Academy/web-layout-training-gulp-master
> ls
README.md app gulpfile.js package-lock.json package.json
```
## npm install 開始後遇到的問題
本文記錄在專案資料夾中輸入 `npm install` 開始後遇到的狀況。
專案資料夾的「package.json」有事先寫好很多插件，所以要透過 `npm install` 指令來安裝這些插件。
然後就出現錯誤訊息了 …… 。
### npm install 錯誤 01
根據錯誤訊息，貌似是跟之前版本的 npm 有關？
```
Your cache folder contains root-owned files, due to a bug in
npm ERR! previous versions of npm which has since been addressed
```
```
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /Users/judy/.npm/_cacache/index-v5/7c/84
npm ERR! errno -13
npm ERR!
npm ERR! Your cache folder contains root-owned files, due to a bug in
npm ERR! previous versions of npm which has since been addressed.
npm ERR!
npm ERR! To permanently fix this problem, please run:
npm ERR! sudo chown -R 501:20 "/Users/judy/.npm"
```
訊息中同時也提供了一條解決問題的建議指令。
### 解決方式：
照著輸入下列指令 > 輸入本機電腦密碼
```
sudo chown -R 501:20 "/Users/[目前電腦使用者的名稱]/.npm"
```
密碼輸入通過後顯示 OK。
### npm install 錯誤 02
本來以為解決了，可是再次輸入 `npm install` 後卻出現新的錯誤，好像是說缺少什麼 main 入口？
```
Error: Cannot find module '/Users/judy/Documents/Hex-Academy/web-layout-training-gulp-master/node_modules/tough-cookie/lib/cookie'.
Please verify that the package.json has a valid "main" entry
```
### 解決方式：
- 移除 `node_modules` 資料夾 (我其實沒有刪只是把它從資料夾移出)
- 輸入 `npm i`
- 成功
> **除錯參考資料：**
> 完美解決報錯 `Please verify that the package.json has a valid “main“ entry` 處理方法 : [https://blog.csdn.net/weixin_45329397/article/details/120635510](https://blog.csdn.net/weixin_45329397/article/details/120635510)
> **npm error - verify that the package.json has a valid "main" entry** : [https://stackoverflow.com/questions/64755386/npm-error-verify-that-the-package-json-has-a-valid-main-entry](https://stackoverflow.com/questions/64755386/npm-error-verify-that-the-package-json-has-a-valid-main-entry)
參考資料中文文章的做法，是還有另 package-lock.json 也移除，但是我沒有這樣，我只有移除 node_modules 再輸入 `npm i` 就有出現成功。
### npm install 錯誤 03
輸入完 `npm i` 之後接著顯示 found vulnerabilities。
雖然成功，但警告目前使用的套件 packages 有一些版本太舊，有漏洞 (vulnerabilities)，需要更新。
```
added 1074 packages, and audited 1075 packages in 11s
22 packages are looking for funding
run `npm fund` for details
44 vulnerabilities (1 low, 2 moderate, 31 high, 10 critical)
To address issues that do not require attention, run:
npm audit fix
To address all issues possible (including breaking changes), run:
npm audit fix --force
Some issues need review, and may require choosing
a different dependency.
Run `npm audit` for details.
```
### 解決方式：
有幾種建議的更新方式指令，在參考其他文章後，決定使用 `npm audit fix` 。
> **除錯參考資料：**
> 解決 node 安裝包的安全漏洞 : [https://blog.csdn.net/boheqing_/article/details/113997476](https://blog.csdn.net/boheqing_/article/details/113997476)
> `npm audit fix` ：自動更新相應有安全漏洞的套件， 不會將 package 套件更新到不兼容的版本。
使用 `npm audit fix` 更新後，漏洞減少了，但是還有一些。
```
25 vulnerabilities (1 low, 2 moderate, 17 high, 5 critical)
```
暫且不繼續處理漏洞，先測試 `npm install` 指令看看到底 gulp 插件裝好沒有。
### npm install 成功 > 輸入 gulp 測試安裝成功
終端機輸入 `gulp` 之後確實有成功自動跳出瀏覽器，出現本地端網頁畫面。
### 退出 gulp 模式： 終端機輸入 ctrl+c
終端機開著 ，處於 gulp 模式下時，會一直即時監聽專案資料夾的異動，瀏覽器渲染網頁時不用按重新整理也會即時更新畫面。
使用 gulp 時，不需要再同時使用 Live SASS Compiler 和 Live Server 這兩個 VScode 套件，gulp 就能同時編譯兩者。
要退出 gulp 就輸入 ctrl+c 即可。
稍微要注意的是，只要在 gulp 監聽期間，終端機就要一直開著。
## 將含有 gulp 的本地端原始碼資料夾部署到 GitHub 上
在終端機位於專案資料夾的狀態下，先輸入下列 3 個 git 指令：
```
git init
git add .
git commit -m "first commit"
```
備註：一定要先到 Git 官網安裝好 Git 在電腦上， git 的指令才會有效，否則終端機不認識指令。
最後剩下 2 個 git 指令：
```
git remote add origin [GitHub Repositories Url]
git push -u origin main
```
前一條指令，需要一個上游端的 GitHub Repository 網址，所以先去自己的 GitHub 新增一個公開的 Repository 再把網址複製貼上 [GitHub Repositories Url] 的部分。
後一條指令，把本地端推上遠端的主要分支 master。
```
git push -u origin master
```
小小留意的是，其實 Github 上面原本提供的指令尾巴是 main，不是 master。
```
git push -u origin main
```
**為什麼改名稱？**
教學文章中，下載的指定資料夾，一開始 `git init` 時就顯示為 master ，
我不確定修改主要分支的名稱，對於資料夾內的 gulp 套件，到底有沒有影響，所以選擇讓遠端配合本地端，將主要分支統一都命名為 master。
總之，最後是把指令的 main 改成 master，就能把整個專案資料夾成功推上去 GitHub。
```
git push -u origin master
```
### git push 終端機畫面卡住 ?
遇到一個狀況，輸入 git push 上去時乍看成功，沒有報錯，可是終端機畫面卻運行很久看似卡在最後一步驟。
本來以為是程式當機，所以重開一次終端機再下 `git push` ，跳出警示表示還沒有設定上游，表示前一次部署果然沒有成功。
```
致命錯誤: 目前分支 master 沒有上游分支。
若要推送目前的分支，並將遠端設為上游，請使用
git push --set-upstream origin master
```
依照指示輸入指令後，畫面還是卡住。
```
git push --set-upstream origin master
```
### 解決 git push 卡住
#### 01 ：檢查上游連結 (remote origin)
> **除錯參考資料：**
> git push時卡住（長時間不報錯也不自動退出）https://www.jb51.net/article/273183.htm
**關掉終端機重開，下指令檢查原本給的上游連結**
```
git remote -v
```
#### 02 ：除掉原本設定的上游並重新設定一次
```
git remote rm origin
```
```
git remote add origin [GitHub Repositories Https Url]
```
注意，我這邊貼上的是 Https 版本的網址。
然後再設定一次上游。
```
git push --set-upstream origin master
```
#### 03 ：總算成功設定好遠端上游
雖然不太懂卡住原因為何，但總算成功。
--
**中場休息**
文章前半段是用 git 指令將「原始碼」部署到 master 分支上，
下半段要用 gulp 將「編譯好的網頁」部署到 gh-pages 上。
--
## gulp build
對網頁做一些修改，新增一個 page2.html 之後，`ctrl + c` 解除 gulp 監聽模式，`gulp build` 將網頁相關資料編譯整理起來，最後一步透過 `gulp deploy` 將編譯過的網頁部署到 gh-pages 上。
但是 …
### gulp deploy 出現錯誤：Error in plugin 'gulp-gh-pages’
錯誤訊息很長，乍看會以為是跟遠端上游設定和 git pull 有關係，
但其實真正關鍵在於「Error in plugin 'gulp-gh-pages’」這一句。
```
> gulp deploy
Current mode：dev
[18:26:06] Using gulpfile ~/Documents/Hex-Academy/web-layout-training-gulp-master/gulpfile.js
[18:26:06] Starting 'deploy'...
[18:26:06] [gh-pages] Cloning repo
[18:26:06] [gh-pages] Checkout branch `gh-pages`
[18:26:06] [gh-pages] Updating repository
[18:26:07] 'deploy' errored after 1.22 s
[18:26:07] Error in plugin 'gulp-gh-pages'
Message:
Command failed: git pull
Details:
killed: false
code: 1
signal: null
cmd: git pull
domainEmitter: [object Object]
domainThrown: false
```
爬文測試後，
### 解決方式：刪除整個 `.publish` 資料夾，再重新輸入 `gulp deploy` 即可。
> **除錯參考資料：**
> gulp-gh-pages deploy 失敗QQ | 程式筆記 - 001 : [https://kevinshu1995.github.io/blog/codingnotes/gulp-gh-pages-deploy-failed-QQ-codingnotes-001/](https://kevinshu1995.github.io/blog/codingnotes/gulp-gh-pages-deploy-failed-QQ-codingnotes-001/)
>
> Troubleshooting : [https://github.com/GovLab/ogrx-2](https://github.com/GovLab/ogrx-2)
> The gulp-gh-pages plugin stores a cache of the repo automatically in a .publish folder, which throws this error when you try to deploy after deleting your gh-pages branch.
:::info
.publish 資料夾是什麼？
:::
.publish 是一個隱藏資料夾，藏在專案資料夾的根部。
終端機指令下 ls -a 列出所有資料夾（包含隱藏的資料夾）就可以找到它。
如果是 mac 使用者，也可在 finder 中輸入鍵盤快捷鍵 ```cmd + shit + .``` (點點是有大於符號> 的那個案按鍵) 讓隱藏資料夾顯示出來。
錯誤發生的原因，似乎是 gulp-gh-pages plugin 這個插件會自動存一些 repo 的快取在 .publish 資料夾內，好像會因此把建立出來的 gh-pages 分支給刪掉？也才導致後續要接著部署上去 GitHub 時，報錯表示找不到對應的分支。
### 刪除整個.publish 資料夾 → gulp deploy
實際操作時遇到 `gulp deploy` 下完後終端機流程卡住，既沒有報錯也沒有完成的狀態，後來反覆刪除 `.publish` 資料夾，甚至也嘗試刪除 `dist` 資料夾，重新輸入 `gulp build` -> `gulp deploy` ，直到到第四次才成功。
如果有遇到的一樣流程卡卡人，或許可以間隔一陣子再跑指令多試幾次。
順帶一提，
- `dist` 資料夾是，只要終端機處於專案資料夾中輸入 `gulp` 指令處於監聽模式下，檔案若有任何變動，就會自動編譯出 `dist` 資料夾和更新裡面內容。
- `.publish` 資料夾則是 `gulp build` 指令自動產生的，刪除後，只要輸入 `gulp build` 又會自動產生新的出來。
### 總算 gulp deploy 成功
到 GitHub 查看，確實可以看到，編譯過的網頁檔案會放在 gh-pages 分支中。
## 要分清楚部署了「什麼東西」又是部署「給誰」？
### 編譯好的網頁用 gulp deploy 部署到 gh-pages
意思就是，在 `gulp` 模式下監聽時，編譯好的檔案都會存在本地端 dist 資料夾中，而 `gulp deploy` 就是：只把 dist 資料夾內的檔案部署到 gh-pages 分支。
部署成功後，到對應的 GitHub Repository 的 Settings > Pages 裡面查看，就會看到 gh-pages 對外展示網頁的網址。
**Your site is live at [https://judy-nihao.github.io/gulp/](https://judy-nihao.github.io/gulp/)**
( 有時候點進去 Pages 裡面沒看到網址，可以過個 5 ~ 10 分鐘後再試試看，應該就會有了。)
### 原始碼用 git 指令另外手動部署在 master 分支中
如果要更新 master 分支的原始碼內容，是另外用一般 git 指令 push 上去。
``git status`` -> ``git add .`` -> ``git commit -m ”文字敘述做了什麼”`` -> ``git push``
大致上除錯紀錄到此，gulp 安裝成功，能夠順利將本地端的檔案部署上去 Github 的 Repository 的對應分支中。
Sign in with Wallet
Connect another wallet