試JavaScript必備：Shell基礎(chǔ)、管道、環(huán)境變量與進(jìn)程管理實(shí)戰(zhàn))
終端里折騰 JavaScript 的時(shí)候你有沒有遇到過這種情況代碼邏輯本身沒什么大問題但命令行敲下去就是一堆看不懂的報(bào)錯(cuò)排查了半天最后發(fā)現(xiàn)是 Shell 基礎(chǔ)不過關(guān)。路徑里有個(gè)空格沒加引號、環(huán)境變量沒生效、管道拼接順序不對、CtrlC 按了沒反應(yīng)導(dǎo)致調(diào)試進(jìn)程一直掛著——這些場景每天都在真實(shí)發(fā)生而且大部分教程默認(rèn)你已經(jīng)會(huì)了根本不會(huì)展開講。這篇博文就把 Shell 語言的基礎(chǔ)知識放在“JavaScript 調(diào)試終端”這個(gè)具體場景里重新梳理一遍。我會(huì)從實(shí)際操作出發(fā)講清楚在終端里調(diào)試 JS 時(shí)最常用的 Shell 概念、命令組合方式以及踩過坑之后才真正明白的細(xì)節(jié)。它適合剛?cè)腴T前端、全棧開發(fā)的同學(xué)也適合寫了很久代碼但 Shell 一直“夠用就行”的老手——說不定能幫你補(bǔ)上幾個(gè)盲點(diǎn)。1. Shell 基礎(chǔ)認(rèn)知調(diào)試 JS 前要搞懂的幾個(gè)底層邏輯1.1 為什么調(diào)試 JS 需要懂 Shell很多同學(xué)的思路是這樣的JavaScript 是編程語言Shell 是命令行兩者好像沒什么關(guān)系。但真到了開發(fā)調(diào)試階段你會(huì)發(fā)現(xiàn)這個(gè)想法很快就會(huì)被現(xiàn)實(shí)打臉。無論是 npm 安裝依賴、啟動(dòng)開發(fā)服務(wù)器、跑單元測試還是查看日志、排查接口報(bào)錯(cuò)每一個(gè)環(huán)節(jié)本質(zhì)上都是在 Shell 環(huán)境里完成的。Node.js 本身就是一個(gè)命令行工具它從 Shell 啟動(dòng)、往 Shell 的標(biāo)準(zhǔn)輸出寫日志、通過退出碼告訴 Shell 這次運(yùn)行是成功還是失敗。不懂 Shell 的底層邏輯很多報(bào)錯(cuò)在你眼里就是玄學(xué)。舉個(gè)最簡單的例子。我寫一個(gè)測試腳本 test.js// test.js console.log(這是一條正常日志); console.error(這是一條錯(cuò)誤信息);在終端執(zhí)行node test.js兩行字都會(huì)打印到屏幕上。但如果執(zhí)行node test.js output.txt你會(huì)驚訝地發(fā)現(xiàn)終端里只剩下一行“這是一條錯(cuò)誤信息”“這是一條正常日志”被寫進(jìn)了文件。原因在于 Shell 里標(biāo)準(zhǔn)輸出和標(biāo)準(zhǔn)錯(cuò)誤是兩條獨(dú)立的通道默認(rèn)只重定向標(biāo)準(zhǔn)輸出不重定向標(biāo)準(zhǔn)錯(cuò)誤。不明白這個(gè)機(jī)制你很可能在調(diào)試時(shí)找不到“消失”的日志文件甚至誤以為代碼根本沒有執(zhí)行到那一行。再比如退出碼。Shell 中每條命令執(zhí)行完都會(huì)返回一個(gè)數(shù)字0 代表成功非 0 代表失敗。你可以用echo $?查看上一條命令的退出碼。寫自動(dòng)化腳本時(shí)經(jīng)常要用和||來根據(jù)退出碼做邏輯拼接。調(diào)試 JS 程序時(shí)未捕獲的異常通常會(huì)讓 Node 進(jìn)程以退出碼 1 結(jié)束于是你的 Shell 腳本會(huì)順著||的路徑繼續(xù)執(zhí)行清理邏輯。這個(gè)聯(lián)動(dòng)機(jī)制就是 Shell 與 JavaScript 協(xié)作的基礎(chǔ)。1.2 別再把 Shell、終端、命令行混為一談我在帶新人時(shí)幾乎每次都會(huì)發(fā)現(xiàn)他們把“終端”“命令行”“Shell”當(dāng)成同一個(gè)東西。這樣理解問題不大但在排查具體問題時(shí)就會(huì)迷糊。比如有人問“為什么我在終端里輸入 node 命令抱 command not found”如果你把終端、命令行、Shell 混在一起就很難定位問題到底出在哪一層。簡單做個(gè)區(qū)分終端準(zhǔn)確說是終端模擬器是一個(gè)界面程序負(fù)責(zé)接收你的鍵盤輸入并把結(jié)果顯示到屏幕上。macOS 自帶的 Terminal、Windows 上的終端工具、VS Code 內(nèi)置的終端面板都屬于終端模擬器。命令行是交互方式就是你打開終端后敲命令、按回車、看到輸出這樣一個(gè)交互過程。Shell 才是真正解析命令、查找程序、執(zhí)行程序的解釋器。它收到你敲入的字符串之后按語法去拆分、判斷然后找到對應(yīng)的可執(zhí)行文件并啟動(dòng)它。打個(gè)生活化的比方終端是廚房的傳菜窗口Shell 是后廚的廚師長命令行是顧客遞進(jìn)來的點(diǎn)菜單而 node 就是后廚里的一臺烤箱。你通過傳菜窗口遞菜單廚師長按菜單內(nèi)容調(diào)用烤箱。表面上看你在“窗口”干活真正干活的是廚師長。調(diào)試 JavaScript 時(shí)理解這層關(guān)系尤其重要。比如你改了環(huán)境變量之后發(fā)現(xiàn)終端里沒有生效其實(shí)是因?yàn)楫?dāng)前終端窗口里的 Shell 進(jìn)程還保留著舊的環(huán)境變量快照需要重新加載配置文件或者新開一個(gè)窗口Shell 才會(huì)重新讀取環(huán)境變量。如果你不清楚 Shell 是一個(gè)常駐進(jìn)程光在終端里反復(fù)輸命令是沒用的。1.3 環(huán)境變量與 PATH 機(jī)制命令為什么能被找到在調(diào)試終端里敲node -vShell 是怎么定位到 node 可執(zhí)行文件的答案就在 PATH 環(huán)境變量里。PATH 是一個(gè)用冒號分隔的目錄列表Shell 拿到命令名時(shí)會(huì)按照這個(gè)列表挨個(gè)目錄去查找匹配的可執(zhí)行文件找到就運(yùn)行全找不到就報(bào)command not found。你可以用echo $PATH查看當(dāng)前路徑列表用which node查看 Shell 實(shí)際執(zhí)行的是哪個(gè) node 文件。這一步在多版本 Node 切換時(shí)特別重要。我見過不少同學(xué)裝了 nvm 管理 Node 版本結(jié)果切換之后node -v顯示的版本沒變一查才發(fā)現(xiàn)是系統(tǒng)目錄里的舊版本優(yōu)先級更高排在 nvm 軟鏈接目錄前面。調(diào)整 PATH 順序或者檢查 npm 全局目錄是否覆蓋了 nvm 的軟鏈問題很快就解決了。對 JavaScript 調(diào)試來說PATH 還有一個(gè)容易被忽略的衍生問題node_modules/.bin目錄。平時(shí)執(zhí)行npm run dev時(shí)npm 會(huì)臨時(shí)把node_modules/.bin加到 PATH 的最前面這樣你才能在 npm scripts 里直接寫webpack --config webpack.config.js而不必寫完整路徑。明白了這一點(diǎn)你就知道為什么有時(shí)候“npm scripts 里能跑命令但手敲同樣的命令卻報(bào) command not found”——因?yàn)槟惝?dāng)前的 Shell 并沒有自動(dòng)找到node_modules/.bin。2. 調(diào)試終端里的高頻 Shell 操作與實(shí)操細(xì)節(jié)2.1 目錄切換與文件定位的實(shí)用技巧調(diào)試 JS 項(xiàng)目時(shí)最常見的操作就是在項(xiàng)目目錄、配置文件目錄、日志目錄之間來回切換?；A(chǔ)的pwd、cd、ls誰都會(huì)用但有幾個(gè)細(xì)節(jié)可能很多老手都沒注意。cd -可以跳回上一次所在的目錄在調(diào)試時(shí)頻繁地在工作目錄和配置文件目錄之間切換這個(gè)命令能省掉不少重復(fù)輸入。ls -la用來查看隱藏文件比如.npmrc、.node_repl_history這類文件平時(shí)不會(huì)出現(xiàn)在默認(rèn)列表里但當(dāng) npm 安裝行為異常、Node REPL 歷史記錄不生效時(shí)它們往往是線索。ls還可以接通配符做過濾比如ls src/**/*.js列出 src 目錄下所有 JS 文件在確認(rèn)“某個(gè)文件到底有沒有被打包”時(shí)很直觀。文件搜索是調(diào)試?yán)锪硪粋€(gè)高頻需求。如果項(xiàng)目很大想快速定位某個(gè)函數(shù)定義在哪個(gè)文件我習(xí)慣用rg而不是grep它默認(rèn)忽略.gitignore里的目錄、性能更好而且輸出帶高亮。基本用法是rg 函數(shù)名 src/。如果你的機(jī)器還沒裝 rg用系統(tǒng)自帶的 find 也能干類似的事find src -name *.js -type f可以列出 src 下所有 JS 文件配合xargs grep 關(guān)鍵詞也能完成搜索只是效率差一些。這里有個(gè)很容易踩的坑路徑里有空格。Shell 默認(rèn)用空格做參數(shù)分隔所以cd ~/My Documents/project會(huì)被拆成兩個(gè)參數(shù)直接報(bào)錯(cuò)。正確處理方式是給路徑加引號cd ~/My Documents/project或者用反斜杠轉(zhuǎn)義空格cd ~/My\ Documents/project。我見過有人因?yàn)闆]處理空格在 Windows 和 macOS 的用戶目錄名里反復(fù)碰壁卻不知道問題出在哪。2.2 管道、重定向與日志排查的配合方式管道的概念很多人其實(shí)一知半解只是知道|能把命令串起來。但真正用好它調(diào)試效率能提升一個(gè)檔次。管道的作用是把左邊命令的標(biāo)準(zhǔn)輸出接到右邊命令的標(biāo)準(zhǔn)輸入讓兩個(gè)原本獨(dú)立的進(jìn)程形成一條處理鏈。比如調(diào)試時(shí)用curl請求接口拿到 JSON直接看一大坨字符串不太方便我一般會(huì)加上jqcurl -s http://localhost:3000/api/user | jq .這樣 JSON 會(huì)格式化輸出還能直接提取字段比如| jq .data.name就能拿到想要的那個(gè)值。左邊 curl 只需專注請求右邊 jq 專注解析職責(zé)分離得很干凈。重定向稍微比管道復(fù)雜一些但核心也就三個(gè)符號覆蓋寫入追加寫入2重定向標(biāo)準(zhǔn)錯(cuò)誤。調(diào)試時(shí)最常用的是把日志同時(shí)輸出到屏幕和文件我一般這樣寫node server.js 21 | tee server.log21表示把標(biāo)準(zhǔn)錯(cuò)誤合并到標(biāo)準(zhǔn)輸出tee則把收到的內(nèi)容一份輸出到屏幕、一份寫入文件。這樣既能在終端實(shí)時(shí)看日志又能留下完整記錄供后續(xù)排查。如果只想在程序崩潰時(shí)保留錯(cuò)誤信息可以用node server.js 2 error.log把錯(cuò)誤通道單獨(dú)落盤。還有一個(gè)細(xì)節(jié)是管道的退出碼問題。默認(rèn)情況下一條管道命令的退出碼由最后一個(gè)命令決定。如果你寫node test.js | grep error就算 node 崩了只要 grep 找到了內(nèi)容整條命令的退出碼就是 0。在需要嚴(yán)格校驗(yàn)每個(gè)步驟是否成功的自動(dòng)化腳本里這會(huì)造成誤判。解決辦法是在 Shell 里開啟set -o pipefail讓管道中任何一個(gè)命令失敗都反映到最終退出碼上這個(gè)習(xí)慣我非常推薦。2.3 后臺運(yùn)行、進(jìn)程管理與 CtrlC 的真正行為調(diào)試 JS 服務(wù)時(shí)經(jīng)常會(huì)遇到想要保持某個(gè)進(jìn)程運(yùn)行、同時(shí)還能繼續(xù)在終端執(zhí)行其他命令的情況。最簡單的做法是在命令末尾加把它放到后臺node server.js server.log 21 注意這里我一定加重定向否則后臺進(jìn)程的日志會(huì)直接打到當(dāng)前終端和之后敲的命令輸出混在一起非?；靵y。啟動(dòng)后可以用jobs查看當(dāng)前 Shell 管理的后臺任務(wù)用fg %1把編號 1 的任務(wù)拉回前臺用bg把它重新放到后臺。如果某個(gè)任務(wù)是前臺阻塞狀態(tài)直接按CtrlZ可以把它掛起再用bg轉(zhuǎn)后臺繼續(xù)運(yùn)行。關(guān)于 CtrlC很多人以為它“終止一切”。準(zhǔn)確地說它向當(dāng)前前臺進(jìn)程組發(fā)送 SIGINT 中斷信號但進(jìn)程可以選擇忽略或攔截。更麻煩的情況是你啟動(dòng)的是 npm scripts它里面又啟動(dòng)了 node 子進(jìn)程。按下 CtrlCnpm 這個(gè)父進(jìn)程是退了但它管理的 node 子進(jìn)程可能沒被清理繼續(xù)占用端口。這就是為什么有時(shí)候改完代碼重啟服務(wù)卻提示端口被占用。遇到這種情況我一般先用ps aux | grep node查看殘留進(jìn)程再用kill 進(jìn)程ID清理而不是直接重啟終端。如果希望進(jìn)程在終端關(guān)閉之后繼續(xù)運(yùn)行可以用nohup配合后臺符號nohup node server.js server.log 21 nohup會(huì)讓進(jìn)程忽略 SIGHUP 掛斷信號這樣即使關(guān)閉終端服務(wù)也還在跑。對應(yīng)清理這類進(jìn)程時(shí)單純按 CtrlC 是沒用的需要重新找到 PID 再kill這一點(diǎn)在線上排查時(shí)特別常見。3. 用 Shell 搭配 JavaScript 調(diào)試的實(shí)戰(zhàn)過程3.1 準(zhǔn)備一個(gè)可反復(fù)調(diào)試的 Node.js 示例光講理論容易飄我用自己的常用手法演示一個(gè)完整的調(diào)試閉環(huán)。假設(shè)我們有一個(gè) Node.js 寫的 HTTP 接口服務(wù)內(nèi)部模擬調(diào)用第三方 API需要?jiǎng)討B(tài)傳參、輸出分色日志、并支持環(huán)境變量控制行為。在實(shí)際調(diào)試中這種場景太常見了——本地聯(lián)調(diào)時(shí)后端接口沒完全就緒前端或者別的調(diào)用方需要先跑通全鏈路。我先把示例代碼寫好保存為 server.js// server.js const http require(http); const port process.env.PORT || 3000; const MODE process.env.MODE || development; const server http.createServer((req, res) { const timestamp new Date().toISOString(); console.log([${timestamp}] 收到請求: ${req.url}); console.error([${timestamp}] 模擬第三方接口耗時(shí)過長...); if (MODE error) { res.statusCode 500; res.end(JSON.stringify({ code: 500, message: 內(nèi)部服務(wù)異常 })); return; } const params new URLSearchParams(req.url.split(?)[1] || ); const name params.get(name) || anonymous; if (name fail) { process.exit(1); } res.setHeader(Content-Type, application/json); res.end(JSON.stringify({ ok: true, name, mode: MODE, port })); }); server.listen(port, () { console.log(服務(wù)已啟動(dòng): http://localhost:${port} 當(dāng)前模式: ${MODE}); });這段代碼里我刻意混入了正常日志和錯(cuò)誤日志還留了環(huán)境變量切換行為和退出碼模擬。調(diào)試的目標(biāo)就是通過 Shell 命令把日志留底、動(dòng)態(tài)切換模式、模擬異常退出并觀察各種情況下的輸出。啟動(dòng)之前先初始化項(xiàng)目并確認(rèn)依賴npm init -y node server.js終端會(huì)打印“服務(wù)已啟動(dòng): http://localhost:3000”。這樣一個(gè)最小可調(diào)試環(huán)境就搭好了。3.2 組合命令完成一個(gè)完整的調(diào)試閉環(huán)現(xiàn)在模擬一次真實(shí)的接口聯(lián)調(diào)。我先讓服務(wù)在后臺跑起來并把日志落盤node server.js server.log 21 然后用 curl 發(fā)起請求curl -s http://localhost:3000/api/user?name張三 | jq .此時(shí)應(yīng)該看到格式化后的 JSON{ ok: true, name: 張三, mode: development, port: 3000 }調(diào)試過程中如果需要同時(shí)觀察請求結(jié)果和日志文件可以用tail -f server.log實(shí)時(shí)追蹤日志變化并在另一個(gè)終端繼續(xù)發(fā)請求。這種“一個(gè)終端看日志、一個(gè)終端發(fā)請求”的模式是我日常排查接口問題的標(biāo)配。如果返回的 JSON 結(jié)構(gòu)太深還可以用 jq 直接過濾比如| jq .data.list[].id提取數(shù)組里的字段不用再復(fù)制到編輯里手動(dòng)格式化。接著模擬一次錯(cuò)誤場景。我故意讓服務(wù)以錯(cuò)誤模式運(yùn)行MODEerror node server.js這個(gè)命令的含義是設(shè)置環(huán)境變量 MODE 為 error然后啟動(dòng)節(jié)點(diǎn)服務(wù)。在終端里可以看到服務(wù)端口輸出的是“當(dāng)前模式: error”請求接口返回 500。如果要避免端口與之前后臺進(jìn)程沖突記得先 kill 掉之前的進(jìn)程再用新端口運(yùn)行PORT4000 MODEerror node server.js這樣既驗(yàn)證了環(huán)境變量參數(shù)化運(yùn)行又實(shí)際演示了通過 Shell 向 Node 進(jìn)程傳參最原始的方式。很多時(shí)候還要把調(diào)試過程中所有輸出匯總到一個(gè)文件方便復(fù)盤。我常用script命令錄制整個(gè)終端會(huì)話或者直接用tee把關(guān)鍵輸出同時(shí)落到文件node server.js 21 | tee /tmp/debug_$(date %Y%m%d_%H%M%S).log這里$(date ...)是命令替換Shell 會(huì)先執(zhí)行 date 得到當(dāng)前時(shí)間戳再把它拼進(jìn)日志文件名。這樣每次調(diào)試日志文件名都是唯一的不會(huì)互相覆蓋后面排查歷史問題特別有用。3.3 Shell 向 JavaScript 傳參與環(huán)境變量的配合上面例子已經(jīng)開始用環(huán)境變量了但很多新手卡在“Shell 向 JS 傳參”這件事上。Node.js 接收參數(shù)主要有兩條路一個(gè)是process.argv一個(gè)是環(huán)境變量。process.argv是命令行參數(shù)數(shù)組。process.argv[0]是 node 路徑process.argv[1]是腳本路徑從process.argv[2]開始才是你真正傳入的參數(shù)。直接運(yùn)行時(shí)這樣傳node server.js --port 5000 --mode debug對應(yīng)代碼里要自己解析 argv。實(shí)際項(xiàng)目里大家多半會(huì)引入?yún)?shù)解析工具比如使用 yargs 或 commander 這類庫但原理都是基于process.argv在解析。真正容易被忽略的是給 npm scripts 傳參。如果你的 package.json 里寫了{(lán) scripts: { start: node server.js } }直接執(zhí)行npm run start --port 5000會(huì)發(fā)現(xiàn)參數(shù)沒生效。原因在于 npm 會(huì)把--port 5000解析成 npm 自己的參數(shù)不會(huì)自動(dòng)透傳給 node。正確的寫法是加--分隔符npm run start -- --port 5000--后面的內(nèi)容會(huì)被原樣傳給腳本然后 node 才能通過process.argv拿到。環(huán)境變量傳參是另一種思路好處是天然不會(huì)被參數(shù)解析庫干擾。Shell 里臨時(shí)設(shè)置環(huán)境變量并啟動(dòng)進(jìn)程的語法是PORT5000 MODEproduction node server.js代碼里用process.env.PORT讀取。這種方式在臨時(shí)聯(lián)調(diào)時(shí)非常方便但是要注意它只在當(dāng)前命令的進(jìn)程環(huán)境里生效不會(huì)影響你當(dāng)前 Shell 其他命令。如果你希望這些變量全局可用就需要寫進(jìn).bashrc或.zshrc或者用export PORT5000顯式導(dǎo)出。在 Windows 上也這樣寫會(huì)直接報(bào)錯(cuò)因?yàn)?set 語法不同?？缙脚_項(xiàng)目里一般用cross-env這類小工具來解決npx cross-env PORT5000 MODEproduction node server.js原理是在跨平臺工具內(nèi)部把環(huán)境變量設(shè)置好再啟動(dòng)子進(jìn)程從而屏蔽掉不同系統(tǒng)之間的差異。我在團(tuán)隊(duì)聯(lián)調(diào)時(shí)經(jīng)常用這個(gè)方案因?yàn)槌蓡T之間操作系統(tǒng)不一致的情況太常見了。4. 常見問題與排查技巧實(shí)錄4.1 command not found 的三種原因command not found大概是調(diào)試終端里出現(xiàn)頻率最高的報(bào)錯(cuò)。我梳理下來無外乎三種原因命令沒安裝、安裝路徑不在 PATH 里、PATH 被額外配置覆蓋了。先排查第一種直接which 命令名看能否找到可執(zhí)行文件找不到就說明沒安裝。第二種比較隱蔽比如你明明用某個(gè)工具安裝了 Node 到自定義目錄卻包 command not found那是因?yàn)檫@個(gè)目錄不在 PATH 里面。第三種常見于 nvm、多版本管理器共存的環(huán)境which node顯示的你以為是 nvm 的路徑實(shí)際卻是系統(tǒng)目錄里另一份舊版本。如果你剛剛修改過配置文件比如.zshrc里新增了export PATH$HOME/.local/bin:$PATH在當(dāng)前終端直接執(zhí)行命令并不會(huì)自動(dòng)生效Shell 不會(huì)因?yàn)槲募兓椭匦录虞d。要么新開一個(gè)終端要么執(zhí)行source ~/.zshrc。source會(huì)把配置文件里的內(nèi)容重新執(zhí)行一遍讓當(dāng)前 Shell 進(jìn)程拿到最新的環(huán)境變量。我經(jīng)常看到有人明明改了 PATH 卻在當(dāng)前終端反復(fù)嘗試?yán)速M(fèi)時(shí)間。4.2 端口被占用與 EADDRINUSE 的處理流程啟動(dòng) Node 服務(wù)時(shí)如果報(bào)Error: listen EADDRINUSE: address already in use :::3000說明端口 3000 已經(jīng)被別的進(jìn)程占用。處理思路很直接先找到占用的進(jìn)程再?zèng)Q定是換端口還是清進(jìn)程。macOS 和 Linux 上我習(xí)慣用lsof -i :3000查看占用情況輸出里能看到 PID。然后kill PID終止進(jìn)程。Windows 上則用netstat -ano | findstr :3000拿到 PID 后用taskkill /PID 編號 /F。這里有個(gè)細(xì)節(jié)要提醒直接kill -9雖然簡單但 SIGKILL 信號不會(huì)給進(jìn)程任何清理機(jī)會(huì)可能會(huì)導(dǎo)致臨時(shí)文件沒刪干凈、端口 Socket 處于半開狀態(tài)。正常情況下建議先發(fā)kill即 SIGTERM讓進(jìn)程自己退出等幾秒沒反應(yīng)再用kill -9。我在維護(hù)本地開發(fā)環(huán)境時(shí)遇到頑固的 node 進(jìn)程一般用pkill -f server.js能按進(jìn)程命令行匹配同時(shí)清理多個(gè)殘留進(jìn)程效率很高。4.3 CtrlC 無效與殘留子進(jìn)程的雙層問題用 npm 啟動(dòng)服務(wù)時(shí)按下CtrlC看著終端回到提示符了以為自己已經(jīng)把服務(wù)停掉了。結(jié)果再去請求接口竟然還有響應(yīng)這就是 npm 腳本和它子進(jìn)程的“雙層進(jìn)程”問題。npm scripts 本質(zhì)上是在 Shell 里再啟動(dòng)一個(gè) Shell 來跑命令命令里又啟動(dòng)了 node。你的 CtrlC 信號默認(rèn)發(fā)給“前臺進(jìn)程組”正常情況下整個(gè)組都會(huì)收到信號。但如果 npm 腳本里用了后臺符號node 子進(jìn)程可能脫離了前臺進(jìn)程組信號就傳不到它那里。殘留進(jìn)程繼續(xù)占著端口后續(xù)更新代碼重啟時(shí)會(huì)莫名其妙地報(bào)端口沖突。遇到這種問題我的排查路徑是先用lsof -i :端口找到殘留 PID確認(rèn)是 node 進(jìn)程再按需清理。如果不想用這么麻煩的方式可以在 npm scripts 里借助進(jìn)程管理工具來統(tǒng)一管理生命周期比如把服務(wù)掛到pm2這類進(jìn)程守護(hù)工具下面停止時(shí)用工具自帶的 stop 命令它會(huì)負(fù)責(zé)把子進(jìn)程樹一并清干凈。或者直接用node --watch server.js這種 Node 自帶的監(jiān)視重啟模式來調(diào)試改代碼后自動(dòng)重啟無需手動(dòng)管理前后臺進(jìn)程。4.4 路徑空格、權(quán)限問題與其他雜項(xiàng)路徑帶空格的問題前面已經(jīng)提過這里強(qiáng)調(diào)一次只要路徑中包含空格、括號等特殊字符要么給整個(gè)路徑加引號要么用反斜杠轉(zhuǎn)義。忘記處理空格在 Windows 系統(tǒng)或者 macOS 中文用戶名下幾乎必然中招而且報(bào)錯(cuò)信息常常讓人摸不著頭腦因?yàn)?Shell 會(huì)把它拆成多個(gè)參數(shù)去執(zhí)行。權(quán)限問題是另一個(gè)高頻坑。當(dāng)你看到EACCES: permission denied時(shí)說明當(dāng)前用戶對文件或目錄沒有寫權(quán)限。先ls -la看屬主和權(quán)限位再用chmod調(diào)整。我的原則是盡量不用sudo因?yàn)橐?root 權(quán)限運(yùn)行 npm install 會(huì)把一堆文件的屬主改成 root后續(xù)普通用戶想改都改不了還得再折騰一圈 chown。真遇到需要全局裝工具包建議先確認(rèn) npm 的全局目錄可寫或者用 nvm 把整個(gè) Node 環(huán)境裝到用戶目錄下從根源上避開系統(tǒng)權(quán)限問題。寫代碼時(shí)還要注意隱藏文件對調(diào)試的影響。比如.npmrc里配置了鏡像源或代理可能導(dǎo)致依賴安裝行為與預(yù)期不同.env文件被某些工具自動(dòng)加載會(huì)讓你的環(huán)境變量“憑空”出現(xiàn)反而掩蓋了傳參問題。調(diào)試時(shí)如果發(fā)現(xiàn)環(huán)境變量跟預(yù)期不符先檢查這兩類文件再懷疑代碼邏輯。5. 高頻命令速查與個(gè)人經(jīng)驗(yàn)補(bǔ)充為了避免讀者邊看邊忘我把前面涉及的常用命令整理成一張速查表可以直接收藏相當(dāng)于在調(diào)試終端里給自己備一份作弊卡。命令用途調(diào)試場景舉例pwd顯示當(dāng)前目錄確認(rèn)工作目錄是否符合預(yù)期cd -回到上一個(gè)目錄在項(xiàng)目目錄和日志目錄間切換ls -la列出全部文件包括隱藏文件檢查 .npmrc、.env 等配置rg 關(guān)鍵詞 目錄快速搜索文件內(nèi)容定位函數(shù)、字符串首次出現(xiàn)的位置echo $?查看上一條命令的退出碼判斷 node 進(jìn)程是否異常退出node xxx.js log 21把標(biāo)準(zhǔn)輸出和錯(cuò)誤一起寫入文件記錄完整調(diào)試日志tail -f log持續(xù)追蹤日志文件實(shí)時(shí)觀察服務(wù)運(yùn)行狀態(tài)curl -s URLjq .字段發(fā)請求并解析 JSONnode xxx.js 后臺運(yùn)行進(jìn)程保持服務(wù)運(yùn)行、騰出終端jobs/fg/bg管理 Shell 后臺任務(wù)前后臺任務(wù)調(diào)換lsof -i :3000查看端口占用排查 EADDRINUSEkill PID發(fā)送中斷信號給進(jìn)程正常停止調(diào)試進(jìn)程pkill -f 關(guān)鍵詞按命令行匹配批量清理進(jìn)程清理殘留 node 進(jìn)程MODEdev node xxx.js用環(huán)境變量控制運(yùn)行區(qū)分調(diào)試/生產(chǎn)模式source ~/.zshrc重新加載 Shell 配置讓新加的 PATH 生效npx cross-env PORT5000 node xxx.js跨平臺設(shè)置環(huán)境變量統(tǒng)一 Windows 與其他系統(tǒng)的傳參最后再分享一個(gè)小技巧調(diào)試 JS 項(xiàng)目時(shí)我會(huì)在終端里長期保留兩個(gè)分屏一個(gè)用于跑服務(wù)和看日志一個(gè)用于發(fā)請求和查控制。左邊窗口常用node server.js 21 | tee debug.log啟動(dòng)右邊窗口用curl配合jq做接口驗(yàn)證。遇到問題優(yōu)先回到基礎(chǔ) Shell 工具去排查——環(huán)境變量、退出碼、管道、端口、權(quán)限這五件事想清楚了能解決開發(fā)調(diào)試中絕大多數(shù)“莫名其妙”的現(xiàn)象。我在實(shí)際工作中發(fā)現(xiàn)很多人以為 Shell 是“知道就行”的冷知識直到出問題才意識到它在日常調(diào)試?yán)镉卸嘀匾?。與其等到卡住了再搜索不如早點(diǎn)把管道、重定向、后臺任務(wù)、環(huán)境變量這幾個(gè)核心機(jī)制摸透它們帶來的效率提升是立竿見影的。 調(diào)試JavaScript必備：Shell基礎(chǔ)、管道、環(huán)境變量與進(jìn)程管理實(shí)戰(zhàn)
終端里折騰 JavaScript 的時(shí)候你有沒有遇到過這種情況代碼邏輯本身沒什么大問題但命令行敲下去就是一堆看不懂的報(bào)錯(cuò)排查了半天最后發(fā)現(xiàn)是 Shell 基礎(chǔ)不過關(guān)。路徑里有個(gè)空格沒加引號、環(huán)境變量沒生效、管道拼接順序不對、CtrlC 按了沒反應(yīng)導(dǎo)致調(diào)試進(jìn)程一直掛著——這些場景每天都在真實(shí)發(fā)生而且大部分教程默認(rèn)你已經(jīng)會(huì)了根本不會(huì)展開講。這篇博文就把 Shell 語言的基礎(chǔ)知識放在“JavaScript 調(diào)試終端”這個(gè)具體場景里重新梳理一遍。我會(huì)從實(shí)際操作出發(fā)講清楚在終端里調(diào)試 JS 時(shí)最常用的 Shell 概念、命令組合方式以及踩過坑之后才真正明白的細(xì)節(jié)。它適合剛?cè)腴T前端、全棧開發(fā)的同學(xué)也適合寫了很久代碼但 Shell 一直“夠用就行”的老手——說不定能幫你補(bǔ)上幾個(gè)盲點(diǎn)。1. Shell 基礎(chǔ)認(rèn)知調(diào)試 JS 前要搞懂的幾個(gè)底層邏輯1.1 為什么調(diào)試 JS 需要懂 Shell很多同學(xué)的思路是這樣的JavaScript 是編程語言Shell 是命令行兩者好像沒什么關(guān)系。但真到了開發(fā)調(diào)試階段你會(huì)發(fā)現(xiàn)這個(gè)想法很快就會(huì)被現(xiàn)實(shí)打臉。無論是 npm 安裝依賴、啟動(dòng)開發(fā)服務(wù)器、跑單元測試還是查看日志、排查接口報(bào)錯(cuò)每一個(gè)環(huán)節(jié)本質(zhì)上都是在 Shell 環(huán)境里完成的。Node.js 本身就是一個(gè)命令行工具它從 Shell 啟動(dòng)、往 Shell 的標(biāo)準(zhǔn)輸出寫日志、通過退出碼告訴 Shell 這次運(yùn)行是成功還是失敗。不懂 Shell 的底層邏輯很多報(bào)錯(cuò)在你眼里就是玄學(xué)。舉個(gè)最簡單的例子。我寫一個(gè)測試腳本 test.js// test.js console.log(這是一條正常日志); console.error(這是一條錯(cuò)誤信息);在終端執(zhí)行node test.js兩行字都會(huì)打印到屏幕上。但如果執(zhí)行node test.js output.txt你會(huì)驚訝地發(fā)現(xiàn)終端里只剩下一行“這是一條錯(cuò)誤信息”“這是一條正常日志”被寫進(jìn)了文件。原因在于 Shell 里標(biāo)準(zhǔn)輸出和標(biāo)準(zhǔn)錯(cuò)誤是兩條獨(dú)立的通道默認(rèn)只重定向標(biāo)準(zhǔn)輸出不重定向標(biāo)準(zhǔn)錯(cuò)誤。不明白這個(gè)機(jī)制你很可能在調(diào)試時(shí)找不到“消失”的日志文件甚至誤以為代碼根本沒有執(zhí)行到那一行。再比如退出碼。Shell 中每條命令執(zhí)行完都會(huì)返回一個(gè)數(shù)字0 代表成功非 0 代表失敗。你可以用echo $?查看上一條命令的退出碼。寫自動(dòng)化腳本時(shí)經(jīng)常要用和||來根據(jù)退出碼做邏輯拼接。調(diào)試 JS 程序時(shí)未捕獲的異常通常會(huì)讓 Node 進(jìn)程以退出碼 1 結(jié)束于是你的 Shell 腳本會(huì)順著||的路徑繼續(xù)執(zhí)行清理邏輯。這個(gè)聯(lián)動(dòng)機(jī)制就是 Shell 與 JavaScript 協(xié)作的基礎(chǔ)。1.2 別再把 Shell、終端、命令行混為一談我在帶新人時(shí)幾乎每次都會(huì)發(fā)現(xiàn)他們把“終端”“命令行”“Shell”當(dāng)成同一個(gè)東西。這樣理解問題不大但在排查具體問題時(shí)就會(huì)迷糊。比如有人問“為什么我在終端里輸入 node 命令抱 command not found”如果你把終端、命令行、Shell 混在一起就很難定位問題到底出在哪一層。簡單做個(gè)區(qū)分終端準(zhǔn)確說是終端模擬器是一個(gè)界面程序負(fù)責(zé)接收你的鍵盤輸入并把結(jié)果顯示到屏幕上。macOS 自帶的 Terminal、Windows 上的終端工具、VS Code 內(nèi)置的終端面板都屬于終端模擬器。命令行是交互方式就是你打開終端后敲命令、按回車、看到輸出這樣一個(gè)交互過程。Shell 才是真正解析命令、查找程序、執(zhí)行程序的解釋器。它收到你敲入的字符串之后按語法去拆分、判斷然后找到對應(yīng)的可執(zhí)行文件并啟動(dòng)它。打個(gè)生活化的比方終端是廚房的傳菜窗口Shell 是后廚的廚師長命令行是顧客遞進(jìn)來的點(diǎn)菜單而 node 就是后廚里的一臺烤箱。你通過傳菜窗口遞菜單廚師長按菜單內(nèi)容調(diào)用烤箱。表面上看你在“窗口”干活真正干活的是廚師長。調(diào)試 JavaScript 時(shí)理解這層關(guān)系尤其重要。比如你改了環(huán)境變量之后發(fā)現(xiàn)終端里沒有生效其實(shí)是因?yàn)楫?dāng)前終端窗口里的 Shell 進(jìn)程還保留著舊的環(huán)境變量快照需要重新加載配置文件或者新開一個(gè)窗口Shell 才會(huì)重新讀取環(huán)境變量。如果你不清楚 Shell 是一個(gè)常駐進(jìn)程光在終端里反復(fù)輸命令是沒用的。1.3 環(huán)境變量與 PATH 機(jī)制命令為什么能被找到在調(diào)試終端里敲node -vShell 是怎么定位到 node 可執(zhí)行文件的答案就在 PATH 環(huán)境變量里。PATH 是一個(gè)用冒號分隔的目錄列表Shell 拿到命令名時(shí)會(huì)按照這個(gè)列表挨個(gè)目錄去查找匹配的可執(zhí)行文件找到就運(yùn)行全找不到就報(bào)command not found。你可以用echo $PATH查看當(dāng)前路徑列表用which node查看 Shell 實(shí)際執(zhí)行的是哪個(gè) node 文件。這一步在多版本 Node 切換時(shí)特別重要。我見過不少同學(xué)裝了 nvm 管理 Node 版本結(jié)果切換之后node -v顯示的版本沒變一查才發(fā)現(xiàn)是系統(tǒng)目錄里的舊版本優(yōu)先級更高排在 nvm 軟鏈接目錄前面。調(diào)整 PATH 順序或者檢查 npm 全局目錄是否覆蓋了 nvm 的軟鏈問題很快就解決了。對 JavaScript 調(diào)試來說PATH 還有一個(gè)容易被忽略的衍生問題node_modules/.bin目錄。平時(shí)執(zhí)行npm run dev時(shí)npm 會(huì)臨時(shí)把node_modules/.bin加到 PATH 的最前面這樣你才能在 npm scripts 里直接寫webpack --config webpack.config.js而不必寫完整路徑。明白了這一點(diǎn)你就知道為什么有時(shí)候“npm scripts 里能跑命令但手敲同樣的命令卻報(bào) command not found”——因?yàn)槟惝?dāng)前的 Shell 并沒有自動(dòng)找到node_modules/.bin。2. 調(diào)試終端里的高頻 Shell 操作與實(shí)操細(xì)節(jié)2.1 目錄切換與文件定位的實(shí)用技巧調(diào)試 JS 項(xiàng)目時(shí)最常見的操作就是在項(xiàng)目目錄、配置文件目錄、日志目錄之間來回切換?；A(chǔ)的pwd、cd、ls誰都會(huì)用但有幾個(gè)細(xì)節(jié)可能很多老手都沒注意。cd -可以跳回上一次所在的目錄在調(diào)試時(shí)頻繁地在工作目錄和配置文件目錄之間切換這個(gè)命令能省掉不少重復(fù)輸入。ls -la用來查看隱藏文件比如.npmrc、.node_repl_history這類文件平時(shí)不會(huì)出現(xiàn)在默認(rèn)列表里但當(dāng) npm 安裝行為異常、Node REPL 歷史記錄不生效時(shí)它們往往是線索。ls還可以接通配符做過濾比如ls src/**/*.js列出 src 目錄下所有 JS 文件在確認(rèn)“某個(gè)文件到底有沒有被打包”時(shí)很直觀。文件搜索是調(diào)試?yán)锪硪粋€(gè)高頻需求。如果項(xiàng)目很大想快速定位某個(gè)函數(shù)定義在哪個(gè)文件我習(xí)慣用rg而不是grep它默認(rèn)忽略.gitignore里的目錄、性能更好而且輸出帶高亮。基本用法是rg 函數(shù)名 src/。如果你的機(jī)器還沒裝 rg用系統(tǒng)自帶的 find 也能干類似的事find src -name *.js -type f可以列出 src 下所有 JS 文件配合xargs grep 關(guān)鍵詞也能完成搜索只是效率差一些。這里有個(gè)很容易踩的坑路徑里有空格。Shell 默認(rèn)用空格做參數(shù)分隔所以cd ~/My Documents/project會(huì)被拆成兩個(gè)參數(shù)直接報(bào)錯(cuò)。正確處理方式是給路徑加引號cd ~/My Documents/project或者用反斜杠轉(zhuǎn)義空格cd ~/My\ Documents/project。我見過有人因?yàn)闆]處理空格在 Windows 和 macOS 的用戶目錄名里反復(fù)碰壁卻不知道問題出在哪。2.2 管道、重定向與日志排查的配合方式管道的概念很多人其實(shí)一知半解只是知道|能把命令串起來。但真正用好它調(diào)試效率能提升一個(gè)檔次。管道的作用是把左邊命令的標(biāo)準(zhǔn)輸出接到右邊命令的標(biāo)準(zhǔn)輸入讓兩個(gè)原本獨(dú)立的進(jìn)程形成一條處理鏈。比如調(diào)試時(shí)用curl請求接口拿到 JSON直接看一大坨字符串不太方便我一般會(huì)加上jqcurl -s http://localhost:3000/api/user | jq .這樣 JSON 會(huì)格式化輸出還能直接提取字段比如| jq .data.name就能拿到想要的那個(gè)值。左邊 curl 只需專注請求右邊 jq 專注解析職責(zé)分離得很干凈。重定向稍微比管道復(fù)雜一些但核心也就三個(gè)符號覆蓋寫入追加寫入2重定向標(biāo)準(zhǔn)錯(cuò)誤。調(diào)試時(shí)最常用的是把日志同時(shí)輸出到屏幕和文件我一般這樣寫node server.js 21 | tee server.log21表示把標(biāo)準(zhǔn)錯(cuò)誤合并到標(biāo)準(zhǔn)輸出tee則把收到的內(nèi)容一份輸出到屏幕、一份寫入文件。這樣既能在終端實(shí)時(shí)看日志又能留下完整記錄供后續(xù)排查。如果只想在程序崩潰時(shí)保留錯(cuò)誤信息可以用node server.js 2 error.log把錯(cuò)誤通道單獨(dú)落盤。還有一個(gè)細(xì)節(jié)是管道的退出碼問題。默認(rèn)情況下一條管道命令的退出碼由最后一個(gè)命令決定。如果你寫node test.js | grep error就算 node 崩了只要 grep 找到了內(nèi)容整條命令的退出碼就是 0。在需要嚴(yán)格校驗(yàn)每個(gè)步驟是否成功的自動(dòng)化腳本里這會(huì)造成誤判。解決辦法是在 Shell 里開啟set -o pipefail讓管道中任何一個(gè)命令失敗都反映到最終退出碼上這個(gè)習(xí)慣我非常推薦。2.3 后臺運(yùn)行、進(jìn)程管理與 CtrlC 的真正行為調(diào)試 JS 服務(wù)時(shí)經(jīng)常會(huì)遇到想要保持某個(gè)進(jìn)程運(yùn)行、同時(shí)還能繼續(xù)在終端執(zhí)行其他命令的情況。最簡單的做法是在命令末尾加把它放到后臺node server.js server.log 21 注意這里我一定加重定向否則后臺進(jìn)程的日志會(huì)直接打到當(dāng)前終端和之后敲的命令輸出混在一起非?；靵y。啟動(dòng)后可以用jobs查看當(dāng)前 Shell 管理的后臺任務(wù)用fg %1把編號 1 的任務(wù)拉回前臺用bg把它重新放到后臺。如果某個(gè)任務(wù)是前臺阻塞狀態(tài)直接按CtrlZ可以把它掛起再用bg轉(zhuǎn)后臺繼續(xù)運(yùn)行。關(guān)于 CtrlC很多人以為它“終止一切”。準(zhǔn)確地說它向當(dāng)前前臺進(jìn)程組發(fā)送 SIGINT 中斷信號但進(jìn)程可以選擇忽略或攔截。更麻煩的情況是你啟動(dòng)的是 npm scripts它里面又啟動(dòng)了 node 子進(jìn)程。按下 CtrlCnpm 這個(gè)父進(jìn)程是退了但它管理的 node 子進(jìn)程可能沒被清理繼續(xù)占用端口。這就是為什么有時(shí)候改完代碼重啟服務(wù)卻提示端口被占用。遇到這種情況我一般先用ps aux | grep node查看殘留進(jìn)程再用kill 進(jìn)程ID清理而不是直接重啟終端。如果希望進(jìn)程在終端關(guān)閉之后繼續(xù)運(yùn)行可以用nohup配合后臺符號nohup node server.js server.log 21 nohup會(huì)讓進(jìn)程忽略 SIGHUP 掛斷信號這樣即使關(guān)閉終端服務(wù)也還在跑。對應(yīng)清理這類進(jìn)程時(shí)單純按 CtrlC 是沒用的需要重新找到 PID 再kill這一點(diǎn)在線上排查時(shí)特別常見。3. 用 Shell 搭配 JavaScript 調(diào)試的實(shí)戰(zhàn)過程3.1 準(zhǔn)備一個(gè)可反復(fù)調(diào)試的 Node.js 示例光講理論容易飄我用自己的常用手法演示一個(gè)完整的調(diào)試閉環(huán)。假設(shè)我們有一個(gè) Node.js 寫的 HTTP 接口服務(wù)內(nèi)部模擬調(diào)用第三方 API需要?jiǎng)討B(tài)傳參、輸出分色日志、并支持環(huán)境變量控制行為。在實(shí)際調(diào)試中這種場景太常見了——本地聯(lián)調(diào)時(shí)后端接口沒完全就緒前端或者別的調(diào)用方需要先跑通全鏈路。我先把示例代碼寫好保存為 server.js// server.js const http require(http); const port process.env.PORT || 3000; const MODE process.env.MODE || development; const server http.createServer((req, res) { const timestamp new Date().toISOString(); console.log([${timestamp}] 收到請求: ${req.url}); console.error([${timestamp}] 模擬第三方接口耗時(shí)過長...); if (MODE error) { res.statusCode 500; res.end(JSON.stringify({ code: 500, message: 內(nèi)部服務(wù)異常 })); return; } const params new URLSearchParams(req.url.split(?)[1] || ); const name params.get(name) || anonymous; if (name fail) { process.exit(1); } res.setHeader(Content-Type, application/json); res.end(JSON.stringify({ ok: true, name, mode: MODE, port })); }); server.listen(port, () { console.log(服務(wù)已啟動(dòng): http://localhost:${port} 當(dāng)前模式: ${MODE}); });這段代碼里我刻意混入了正常日志和錯(cuò)誤日志還留了環(huán)境變量切換行為和退出碼模擬。調(diào)試的目標(biāo)就是通過 Shell 命令把日志留底、動(dòng)態(tài)切換模式、模擬異常退出并觀察各種情況下的輸出。啟動(dòng)之前先初始化項(xiàng)目并確認(rèn)依賴npm init -y node server.js終端會(huì)打印“服務(wù)已啟動(dòng): http://localhost:3000”。這樣一個(gè)最小可調(diào)試環(huán)境就搭好了。3.2 組合命令完成一個(gè)完整的調(diào)試閉環(huán)現(xiàn)在模擬一次真實(shí)的接口聯(lián)調(diào)。我先讓服務(wù)在后臺跑起來并把日志落盤node server.js server.log 21 然后用 curl 發(fā)起請求curl -s http://localhost:3000/api/user?name張三 | jq .此時(shí)應(yīng)該看到格式化后的 JSON{ ok: true, name: 張三, mode: development, port: 3000 }調(diào)試過程中如果需要同時(shí)觀察請求結(jié)果和日志文件可以用tail -f server.log實(shí)時(shí)追蹤日志變化并在另一個(gè)終端繼續(xù)發(fā)請求。這種“一個(gè)終端看日志、一個(gè)終端發(fā)請求”的模式是我日常排查接口問題的標(biāo)配。如果返回的 JSON 結(jié)構(gòu)太深還可以用 jq 直接過濾比如| jq .data.list[].id提取數(shù)組里的字段不用再復(fù)制到編輯里手動(dòng)格式化。接著模擬一次錯(cuò)誤場景。我故意讓服務(wù)以錯(cuò)誤模式運(yùn)行MODEerror node server.js這個(gè)命令的含義是設(shè)置環(huán)境變量 MODE 為 error然后啟動(dòng)節(jié)點(diǎn)服務(wù)。在終端里可以看到服務(wù)端口輸出的是“當(dāng)前模式: error”請求接口返回 500。如果要避免端口與之前后臺進(jìn)程沖突記得先 kill 掉之前的進(jìn)程再用新端口運(yùn)行PORT4000 MODEerror node server.js這樣既驗(yàn)證了環(huán)境變量參數(shù)化運(yùn)行又實(shí)際演示了通過 Shell 向 Node 進(jìn)程傳參最原始的方式。很多時(shí)候還要把調(diào)試過程中所有輸出匯總到一個(gè)文件方便復(fù)盤。我常用script命令錄制整個(gè)終端會(huì)話或者直接用tee把關(guān)鍵輸出同時(shí)落到文件node server.js 21 | tee /tmp/debug_$(date %Y%m%d_%H%M%S).log這里$(date ...)是命令替換Shell 會(huì)先執(zhí)行 date 得到當(dāng)前時(shí)間戳再把它拼進(jìn)日志文件名。這樣每次調(diào)試日志文件名都是唯一的不會(huì)互相覆蓋后面排查歷史問題特別有用。3.3 Shell 向 JavaScript 傳參與環(huán)境變量的配合上面例子已經(jīng)開始用環(huán)境變量了但很多新手卡在“Shell 向 JS 傳參”這件事上。Node.js 接收參數(shù)主要有兩條路一個(gè)是process.argv一個(gè)是環(huán)境變量。process.argv是命令行參數(shù)數(shù)組。process.argv[0]是 node 路徑process.argv[1]是腳本路徑從process.argv[2]開始才是你真正傳入的參數(shù)。直接運(yùn)行時(shí)這樣傳node server.js --port 5000 --mode debug對應(yīng)代碼里要自己解析 argv。實(shí)際項(xiàng)目里大家多半會(huì)引入?yún)?shù)解析工具比如使用 yargs 或 commander 這類庫但原理都是基于process.argv在解析。真正容易被忽略的是給 npm scripts 傳參。如果你的 package.json 里寫了{(lán) scripts: { start: node server.js } }直接執(zhí)行npm run start --port 5000會(huì)發(fā)現(xiàn)參數(shù)沒生效。原因在于 npm 會(huì)把--port 5000解析成 npm 自己的參數(shù)不會(huì)自動(dòng)透傳給 node。正確的寫法是加--分隔符npm run start -- --port 5000--后面的內(nèi)容會(huì)被原樣傳給腳本然后 node 才能通過process.argv拿到。環(huán)境變量傳參是另一種思路好處是天然不會(huì)被參數(shù)解析庫干擾。Shell 里臨時(shí)設(shè)置環(huán)境變量并啟動(dòng)進(jìn)程的語法是PORT5000 MODEproduction node server.js代碼里用process.env.PORT讀取。這種方式在臨時(shí)聯(lián)調(diào)時(shí)非常方便但是要注意它只在當(dāng)前命令的進(jìn)程環(huán)境里生效不會(huì)影響你當(dāng)前 Shell 其他命令。如果你希望這些變量全局可用就需要寫進(jìn).bashrc或.zshrc或者用export PORT5000顯式導(dǎo)出。在 Windows 上也這樣寫會(huì)直接報(bào)錯(cuò)因?yàn)?set 語法不同?？缙脚_項(xiàng)目里一般用cross-env這類小工具來解決npx cross-env PORT5000 MODEproduction node server.js原理是在跨平臺工具內(nèi)部把環(huán)境變量設(shè)置好再啟動(dòng)子進(jìn)程從而屏蔽掉不同系統(tǒng)之間的差異。我在團(tuán)隊(duì)聯(lián)調(diào)時(shí)經(jīng)常用這個(gè)方案因?yàn)槌蓡T之間操作系統(tǒng)不一致的情況太常見了。4. 常見問題與排查技巧實(shí)錄4.1 command not found 的三種原因command not found大概是調(diào)試終端里出現(xiàn)頻率最高的報(bào)錯(cuò)。我梳理下來無外乎三種原因命令沒安裝、安裝路徑不在 PATH 里、PATH 被額外配置覆蓋了。先排查第一種直接which 命令名看能否找到可執(zhí)行文件找不到就說明沒安裝。第二種比較隱蔽比如你明明用某個(gè)工具安裝了 Node 到自定義目錄卻包 command not found那是因?yàn)檫@個(gè)目錄不在 PATH 里面。第三種常見于 nvm、多版本管理器共存的環(huán)境which node顯示的你以為是 nvm 的路徑實(shí)際卻是系統(tǒng)目錄里另一份舊版本。如果你剛剛修改過配置文件比如.zshrc里新增了export PATH$HOME/.local/bin:$PATH在當(dāng)前終端直接執(zhí)行命令并不會(huì)自動(dòng)生效Shell 不會(huì)因?yàn)槲募兓椭匦录虞d。要么新開一個(gè)終端要么執(zhí)行source ~/.zshrc。source會(huì)把配置文件里的內(nèi)容重新執(zhí)行一遍讓當(dāng)前 Shell 進(jìn)程拿到最新的環(huán)境變量。我經(jīng)常看到有人明明改了 PATH 卻在當(dāng)前終端反復(fù)嘗試?yán)速M(fèi)時(shí)間。4.2 端口被占用與 EADDRINUSE 的處理流程啟動(dòng) Node 服務(wù)時(shí)如果報(bào)Error: listen EADDRINUSE: address already in use :::3000說明端口 3000 已經(jīng)被別的進(jìn)程占用。處理思路很直接先找到占用的進(jìn)程再?zèng)Q定是換端口還是清進(jìn)程。macOS 和 Linux 上我習(xí)慣用lsof -i :3000查看占用情況輸出里能看到 PID。然后kill PID終止進(jìn)程。Windows 上則用netstat -ano | findstr :3000拿到 PID 后用taskkill /PID 編號 /F。這里有個(gè)細(xì)節(jié)要提醒直接kill -9雖然簡單但 SIGKILL 信號不會(huì)給進(jìn)程任何清理機(jī)會(huì)可能會(huì)導(dǎo)致臨時(shí)文件沒刪干凈、端口 Socket 處于半開狀態(tài)。正常情況下建議先發(fā)kill即 SIGTERM讓進(jìn)程自己退出等幾秒沒反應(yīng)再用kill -9。我在維護(hù)本地開發(fā)環(huán)境時(shí)遇到頑固的 node 進(jìn)程一般用pkill -f server.js能按進(jìn)程命令行匹配同時(shí)清理多個(gè)殘留進(jìn)程效率很高。4.3 CtrlC 無效與殘留子進(jìn)程的雙層問題用 npm 啟動(dòng)服務(wù)時(shí)按下CtrlC看著終端回到提示符了以為自己已經(jīng)把服務(wù)停掉了。結(jié)果再去請求接口竟然還有響應(yīng)這就是 npm 腳本和它子進(jìn)程的“雙層進(jìn)程”問題。npm scripts 本質(zhì)上是在 Shell 里再啟動(dòng)一個(gè) Shell 來跑命令命令里又啟動(dòng)了 node。你的 CtrlC 信號默認(rèn)發(fā)給“前臺進(jìn)程組”正常情況下整個(gè)組都會(huì)收到信號。但如果 npm 腳本里用了后臺符號node 子進(jìn)程可能脫離了前臺進(jìn)程組信號就傳不到它那里。殘留進(jìn)程繼續(xù)占著端口后續(xù)更新代碼重啟時(shí)會(huì)莫名其妙地報(bào)端口沖突。遇到這種問題我的排查路徑是先用lsof -i :端口找到殘留 PID確認(rèn)是 node 進(jìn)程再按需清理。如果不想用這么麻煩的方式可以在 npm scripts 里借助進(jìn)程管理工具來統(tǒng)一管理生命周期比如把服務(wù)掛到pm2這類進(jìn)程守護(hù)工具下面停止時(shí)用工具自帶的 stop 命令它會(huì)負(fù)責(zé)把子進(jìn)程樹一并清干凈。或者直接用node --watch server.js這種 Node 自帶的監(jiān)視重啟模式來調(diào)試改代碼后自動(dòng)重啟無需手動(dòng)管理前后臺進(jìn)程。4.4 路徑空格、權(quán)限問題與其他雜項(xiàng)路徑帶空格的問題前面已經(jīng)提過這里強(qiáng)調(diào)一次只要路徑中包含空格、括號等特殊字符要么給整個(gè)路徑加引號要么用反斜杠轉(zhuǎn)義。忘記處理空格在 Windows 系統(tǒng)或者 macOS 中文用戶名下幾乎必然中招而且報(bào)錯(cuò)信息常常讓人摸不著頭腦因?yàn)?Shell 會(huì)把它拆成多個(gè)參數(shù)去執(zhí)行。權(quán)限問題是另一個(gè)高頻坑。當(dāng)你看到EACCES: permission denied時(shí)說明當(dāng)前用戶對文件或目錄沒有寫權(quán)限。先ls -la看屬主和權(quán)限位再用chmod調(diào)整。我的原則是盡量不用sudo因?yàn)橐?root 權(quán)限運(yùn)行 npm install 會(huì)把一堆文件的屬主改成 root后續(xù)普通用戶想改都改不了還得再折騰一圈 chown。真遇到需要全局裝工具包建議先確認(rèn) npm 的全局目錄可寫或者用 nvm 把整個(gè) Node 環(huán)境裝到用戶目錄下從根源上避開系統(tǒng)權(quán)限問題。寫代碼時(shí)還要注意隱藏文件對調(diào)試的影響。比如.npmrc里配置了鏡像源或代理可能導(dǎo)致依賴安裝行為與預(yù)期不同.env文件被某些工具自動(dòng)加載會(huì)讓你的環(huán)境變量“憑空”出現(xiàn)反而掩蓋了傳參問題。調(diào)試時(shí)如果發(fā)現(xiàn)環(huán)境變量跟預(yù)期不符先檢查這兩類文件再懷疑代碼邏輯。5. 高頻命令速查與個(gè)人經(jīng)驗(yàn)補(bǔ)充為了避免讀者邊看邊忘我把前面涉及的常用命令整理成一張速查表可以直接收藏相當(dāng)于在調(diào)試終端里給自己備一份作弊卡。命令用途調(diào)試場景舉例pwd顯示當(dāng)前目錄確認(rèn)工作目錄是否符合預(yù)期cd -回到上一個(gè)目錄在項(xiàng)目目錄和日志目錄間切換ls -la列出全部文件包括隱藏文件檢查 .npmrc、.env 等配置rg 關(guān)鍵詞 目錄快速搜索文件內(nèi)容定位函數(shù)、字符串首次出現(xiàn)的位置echo $?查看上一條命令的退出碼判斷 node 進(jìn)程是否異常退出node xxx.js log 21把標(biāo)準(zhǔn)輸出和錯(cuò)誤一起寫入文件記錄完整調(diào)試日志tail -f log持續(xù)追蹤日志文件實(shí)時(shí)觀察服務(wù)運(yùn)行狀態(tài)curl -s URLjq .字段發(fā)請求并解析 JSONnode xxx.js 后臺運(yùn)行進(jìn)程保持服務(wù)運(yùn)行、騰出終端jobs/fg/bg管理 Shell 后臺任務(wù)前后臺任務(wù)調(diào)換lsof -i :3000查看端口占用排查 EADDRINUSEkill PID發(fā)送中斷信號給進(jìn)程正常停止調(diào)試進(jìn)程pkill -f 關(guān)鍵詞按命令行匹配批量清理進(jìn)程清理殘留 node 進(jìn)程MODEdev node xxx.js用環(huán)境變量控制運(yùn)行區(qū)分調(diào)試/生產(chǎn)模式source ~/.zshrc重新加載 Shell 配置讓新加的 PATH 生效npx cross-env PORT5000 node xxx.js跨平臺設(shè)置環(huán)境變量統(tǒng)一 Windows 與其他系統(tǒng)的傳參最后再分享一個(gè)小技巧調(diào)試 JS 項(xiàng)目時(shí)我會(huì)在終端里長期保留兩個(gè)分屏一個(gè)用于跑服務(wù)和看日志一個(gè)用于發(fā)請求和查控制。左邊窗口常用node server.js 21 | tee debug.log啟動(dòng)右邊窗口用curl配合jq做接口驗(yàn)證。遇到問題優(yōu)先回到基礎(chǔ) Shell 工具去排查——環(huán)境變量、退出碼、管道、端口、權(quán)限這五件事想清楚了能解決開發(fā)調(diào)試中絕大多數(shù)“莫名其妙”的現(xiàn)象。我在實(shí)際工作中發(fā)現(xiàn)很多人以為 Shell 是“知道就行”的冷知識直到出問題才意識到它在日常調(diào)試?yán)镉卸嘀匾?。與其等到卡住了再搜索不如早點(diǎn)把管道、重定向、后臺任務(wù)、環(huán)境變量這幾個(gè)核心機(jī)制摸透它們帶來的效率提升是立竿見影的。