境安裝到構(gòu)建第一個(gè)Web應(yīng)用)
Node.js 入門教程很多但真正能幫你在 1 小時(shí)內(nèi)把安裝、驗(yàn)證、編碼、跑通全部走完的并不多。這篇文章以“從下載 Node.js 到寫出第一個(gè) Web 應(yīng)用”為主線把 60 分鐘拆成四段前 10 分鐘搞清楚 Node.js 是干什么的、版本怎么選中間 15 分鐘完成安裝和 npm 基礎(chǔ)配置接下來 20 分鐘用 Node.js 自帶模塊寫一個(gè)能訪問的 Web 頁面最后 15 分鐘排查安裝和運(yùn)行時(shí)最常見的報(bào)錯(cuò)。這樣做的好處是每一步都能驗(yàn)證結(jié)果不會(huì)出現(xiàn)“環(huán)境配了一下午代碼一跑全是問題”的情況。1. 先搞清楚 Node.js 是干什么的再?zèng)Q定安裝哪個(gè)版本1.1 Node.js 不是普通腳本工具而是一個(gè) JavaScript 運(yùn)行時(shí)Node.js 的官方定位是“基于 Chrome V8 引擎的 JavaScript 運(yùn)行時(shí)”。通俗一點(diǎn)說瀏覽器給 JavaScript 提供了window、document、fetch等環(huán)境而 Node.js 給 JavaScript 提供了文件讀取、網(wǎng)絡(luò)請(qǐng)求、進(jìn)程管理、操作系統(tǒng)交互等能力。這意味著你不再需要通過 HTML 頁面來運(yùn)行 JavaScript可以直接在終端執(zhí)行node -e console.log(hello node)這行命令會(huì)創(chuàng)建一個(gè) Node.js 進(jìn)程執(zhí)行字符串里的 JavaScript 代碼然后把結(jié)果輸出到控制臺(tái)。對(duì)剛?cè)腴T的人來說只要理解這一點(diǎn)就夠了Node.js 讓 JavaScript 從“只能操作頁面”變成“可以操作文件和網(wǎng)絡(luò)”的通用語言。1.2 事件驅(qū)動(dòng)、非阻塞 I/O 到底影響什么很多資料會(huì)提到“事件驅(qū)動(dòng)”“非阻塞 I/O”“單線程”。這里用一句更貼近實(shí)際的話解釋Node.js 遇到耗時(shí)操作時(shí)不會(huì)一直卡住等待結(jié)果而是先繼續(xù)處理其他請(qǐng)求等耗時(shí)操作完成后通過回調(diào)繼續(xù)處理?？匆粋€(gè)簡單對(duì)比// 模擬耗時(shí)讀取不推薦生產(chǎn)環(huán)境使用 fs.readFileSync const fs require(fs); console.log(1. 開始讀取); const data fs.readFileSync(example.txt, utf8); console.log(2. 讀取完成, data.length); console.log(3. 繼續(xù)執(zhí)行);上面這段用同步方式讀文件執(zhí)行到第二行時(shí)整個(gè)進(jìn)程會(huì)等待文件讀完才繼續(xù)執(zhí)行第三行。如果改用異步方式const fs require(fs); console.log(1. 開始讀取); fs.readFile(example.txt, utf8, (err, data) { console.log(2. 讀取完成, data ? data.length : error); }); console.log(3. 繼續(xù)執(zhí)行);執(zhí)行順序會(huì)變成“1、3、2”。異步 I/O 是 Node.js 能同時(shí)處理大量并發(fā)請(qǐng)求的重要原因。對(duì)于剛?cè)腴T的第一個(gè) Web 應(yīng)用你不需要立刻精通它但必須理解fs.readFile的回調(diào)不會(huì)阻塞后續(xù)代碼。1.3 LTS、Current、偶數(shù)版本號(hào)怎么選安裝 Node.js 前最容易出錯(cuò)的是版本選擇。官方發(fā)布版本大致分兩類版本類型說明適合場景LTSLong Term Support長期支持版本會(huì)持續(xù)維護(hù)和修復(fù)漏洞推薦新手、生產(chǎn)環(huán)境、企業(yè)項(xiàng)目Current當(dāng)前版本包含新特性但迭代快、可能不穩(wěn)定嘗鮮、特性驗(yàn)證、短期學(xué)習(xí)偶數(shù)版本例如 18、20、22通常更容易進(jìn)入 LTS 周期穩(wěn)定性優(yōu)先的項(xiàng)目奇數(shù)版本例如 19、21、23通常是過渡版本不建議作為主力實(shí)際項(xiàng)目里建議安裝當(dāng)前最新 LTS而不是最新 Current。原因很直接很多 npm 包對(duì) Node.js 版本有要求LTS 版本生態(tài)兼容更好遇到問題時(shí)搜索引擎能找到更多答案。1.4 安裝前的環(huán)境檢查清單安裝前先檢查操作系統(tǒng)、CPU 架構(gòu)和是否已存在舊版本# Windows PowerShell systeminfo | findstr /C:OS # Linux / macOS uname -m # 檢查是否已經(jīng)安裝過 Node.js node -v npm -vWindows 下尤其要注意架構(gòu)絕大多數(shù)現(xiàn)代電腦使用 64 位系統(tǒng)應(yīng)該下載x64安裝包部分舊電腦是 32 位系統(tǒng)需要下載x86包。如果系統(tǒng)里已經(jīng)安裝了舊版 Node.js先確認(rèn)版本避免安裝新版本后 PATH 環(huán)境變量混亂。2. 安裝 Node.js 的三種方式以及為什么推薦用 nvm2.1 Windows 圖形化安裝包最快但最不靈活進(jìn)入 Node.js 官網(wǎng)下載頁選擇適合當(dāng)前系統(tǒng)的.msi安裝包雙擊運(yùn)行即可。安裝過程中默認(rèn)已經(jīng)包含“添加到 PATH”選項(xiàng)一般不需要修改一直下一步即可。安裝完成后重新打開一個(gè)終端窗口執(zhí)行node -v npm -v如果輸出類似v22.13.1 10.9.2說明安裝成功。需要注意安裝完成后必須新開終端窗口否則當(dāng)前終端的 PATH 不會(huì)刷新仍然提示找不到node命令。這種方式適合只跑一次 Node.js、不打算切換項(xiàng)目的用戶。缺點(diǎn)是當(dāng)某個(gè)項(xiàng)目依賴 Node.js 20另一個(gè)項(xiàng)目依賴 Node.js 22 時(shí)圖形化安裝包無法靈活切換版本。2.2 Windows 下使用 nvm-windows 管理多版本跨項(xiàng)目開發(fā)時(shí)推薦使用 nvmNode Version Manager管理 Node.js 版本。Windows 上沒有直接移植原版 nvm常用的是 nvm-windows。安裝方式從 nvm-windows 的發(fā)布頁面下載安裝包。安裝到一個(gè)不含中文和空格的目錄例如C:\nvm。安裝完成后終端執(zhí)行nvm version然后安裝并切換 Node.js 版本nvm install 22.13.1 nvm use 22.13.1 node -v執(zhí)行nvm use后node命令會(huì)指向 nvm 管理目錄下的對(duì)應(yīng)版本。這里的關(guān)鍵點(diǎn)是不要直接到官網(wǎng)下載安裝包和管理器混用那會(huì)讓node命令的來源不確定。我的建議是Windows 新項(xiàng)目統(tǒng)一用 nvm-windows即使以后需要升級(jí) Node.js 或同時(shí)維護(hù)舊項(xiàng)目也不會(huì)被版本問題卡住。2.3 macOS/Linux 下的 nvm 安裝macOS 或 Linux 用戶可以使用官方腳本安裝 nvm但不要直接復(fù)制網(wǎng)上來路不明的curl腳本應(yīng)該先檢查內(nèi)容再執(zhí)行。安裝 nvm 后shell 配置文件通常是.zshrc或.bashrc會(huì)追加 nvm 初始化腳本。安裝完成要重新加載配置source ~/.zshrc然后安裝 Node.jsnvm install --lts nvm use --lts node -v--lts會(huì)安裝當(dāng)前最新的長期支持版本避免手動(dòng)指定容易過時(shí)的版本號(hào)。2.4 安裝完成后的檢查點(diǎn)無論使用哪種方式都要完成以下檢查檢查項(xiàng)命令預(yù)期結(jié)果Node.js 可用node -v輸出類似v22.13.1npm 可用npm -v輸出類似10.9.2nvm 可用nvm version輸出 nvm 版本號(hào)全局路徑npm root -g輸出存在的全局 node_modules 目錄緩存路徑npm config get cache輸出 npm 緩存目錄如果node -v能正常輸出但npm -v報(bào)錯(cuò)通常是因?yàn)榘惭b包損壞、PATH 中存在多個(gè) Node.js 目錄或舊版殘留。不要急著重裝先運(yùn)行where nodeWindows或which nodeLinux/macOS確認(rèn)實(shí)際執(zhí)行路徑。3. 用 npm 做基礎(chǔ)配置鏡像源、全局路徑和緩存目錄3.1 npm 的職責(zé)與版本npm 是 Node.js 自帶的包管理器負(fù)責(zé)下載、安裝、卸載第三方依賴并維護(hù)項(xiàng)目的依賴關(guān)系。它和node是兩套程序Node.js 負(fù)責(zé)運(yùn)行 JavaScriptnpm 負(fù)責(zé)管理 JavaScript 需要的庫。npm 的版本通常不等同于 Node.js 版本。安裝 Node.js 后npm 也一并安裝。日常使用中不要只關(guān)注node -v還要關(guān)注npm -v。某些 CLI 工具會(huì)要求 npm 版本達(dá)到閾值如果版本過舊可以通過以下命令升級(jí) npmnpm install -g npmlatest3.2 配置鏡像源避免安裝依賴超時(shí)在實(shí)際網(wǎng)絡(luò)環(huán)境里直接從官方源安裝依賴可能很慢常見表現(xiàn)是npm install長時(shí)間停留在idealTree階段或者直接超時(shí)?？梢园?npm 的 registry 切換到國內(nèi)鏡像npm config set registry https://registry.npmmirror.com/驗(yàn)證是否生效npm config get registry也可以直接查看配置文件位置npm config ls -l這里要注意的是全局使用鏡像源會(huì)影響所有項(xiàng)目。如果某些項(xiàng)目必須使用官方源或公司內(nèi)網(wǎng)源可以只在項(xiàng)目根目錄創(chuàng)建.npmrc寫入registryhttps://registry.npmjs.org/項(xiàng)目級(jí)配置會(huì)覆蓋全局配置。這樣就能做到“全局用鏡像個(gè)別項(xiàng)目用官方源”。3.3 全局安裝路徑和權(quán)限使用全局安裝命令時(shí)npm install -g npm-check-updates全局包會(huì)安裝到npm root -g指向的目錄。Windows 下全局命令通常會(huì)被軟鏈到 npm 前綴目錄如果沒有正確配置會(huì)出現(xiàn)“命令安裝成功但終端找不到”的問題。Linux/macOS 下如果直接使用npm install -g遇到權(quán)限錯(cuò)誤不要用sudo強(qiáng)行安裝更推薦修改 npm 的全局目錄到用戶目錄下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后在 shell 配置文件中添加export PATH~/.npm-global/bin:$PATH這樣全局安裝的 CLI 工具都可以直接用也避免了權(quán)限污染。3.4 驗(yàn)證 npm 配置配置完成后創(chuàng)建一個(gè)臨時(shí)目錄測試 npm 是否能正常安裝依賴mkdir npm-config-test cd npm-config-test npm init -y npm install lodash看到node_modules目錄生成并出現(xiàn)package-lock.json說明安裝鏈路正常。檢查點(diǎn)有npm config get registry輸出鏡像地址。npm root -g輸出一個(gè)可寫目錄。npm install沒有權(quán)限和超時(shí)報(bào)錯(cuò)。注意不要在生產(chǎn)環(huán)境隨意使用npm cache clean --force。多數(shù)安裝問題不是緩存損壞而是鏡像源或版本不對(duì)。強(qiáng)行清理緩存反而會(huì)拖慢下一次安裝。4. 創(chuàng)建第一個(gè) Web 應(yīng)用使用內(nèi)置 http 模塊4.1 初始化項(xiàng)目和目錄結(jié)構(gòu)先創(chuàng)建項(xiàng)目目錄mkdir node-first-app cd node-first-app npm init -ynpm init -y會(huì)生成一個(gè)默認(rèn)的package.json內(nèi)容類似于{ name: node-first-app, version: 1.0.0, description: , main: index.js, scripts: { test: echo \Error: no test specified\ exit 1 } }對(duì)于第一個(gè) Web 應(yīng)用這個(gè)文件不是必須修改的但要理解它記錄了三類信息項(xiàng)目名稱與版本、入口文件、啟動(dòng)腳本。后續(xù)添加第三方依賴時(shí)dependencies也會(huì)寫到這里。4.2 最小可運(yùn)行的 HTTP 服務(wù)器新建server.js文件寫入const http require(http); const hostname 127.0.0.1; const port 3000; const server http.createServer((req, res) { res.statusCode 200; res.setHeader(Content-Type, text/plain; charsetutf-8); res.end(Hello Node.js Web App); }); server.listen(port, hostname, () { console.log(Server running at http://${hostname}:${port}/); });這段代碼的每一行都有明確作用require(http)導(dǎo)入 Node.js 內(nèi)置的 HTTP 模塊。http.createServer接收一個(gè)回調(diào)函數(shù)每次有請(qǐng)求進(jìn)來都會(huì)執(zhí)行。req是請(qǐng)求對(duì)象包含 URL、請(qǐng)求方法、請(qǐng)求頭。res是響應(yīng)對(duì)象用來設(shè)置狀態(tài)碼、響應(yīng)頭和響應(yīng)體。listening是網(wǎng)絡(luò)層面的監(jiān)聽端口這里指定127.0.0.1:3000。4.3 解析請(qǐng)求參數(shù)和返回 JSON第一個(gè) Web 應(yīng)用如果只有“Hello World”還看不出實(shí)用價(jià)值。擴(kuò)展一下根據(jù) URL 返回用戶信息。const http require(http); const url require(url); const server http.createServer((req, res) { const parsedUrl new URL(req.url, http://${req.headers.host}); const pathname parsedUrl.pathname; res.setHeader(Content-Type, application/json; charsetutf-8); if (req.method GET pathname /user) { const name parsedUrl.searchParams.get(name) || anonymous; res.statusCode 200; res.end( JSON.stringify({ code: 0, data: { name, time: new Date().toISOString() } }) ); return; } res.statusCode 404; res.end(JSON.stringify({ code: 404, message: Not Found })); }); server.listen(3000, 127.0.0.1, () { console.log(Server running at http://127.0.0.1:3000/); });訪問http://127.0.0.1:3000/user?namenode返回{code:0,data:{name:node,time:2025-01-01T12:00:00.000Z}}這里用到了URL對(duì)象是 Node.js 內(nèi)置的 URL 解析方式。比手動(dòng)拆分字符串更可靠也能處理中文參數(shù)、編碼問題。4.4 啟動(dòng)服務(wù)和驗(yàn)證接口執(zhí)行node server.js輸出Server running at http://127.0.0.1:3000/然后打開瀏覽器訪問http://127.0.0.1:3000/user?namenode或者用命令行驗(yàn)證curl http://127.0.0.1:3000/user?namenode注意curl在 Windows PowerShell 中默認(rèn)可能是Invoke-WebRequest的別名。如果輸出格式不同可以改用curl.exe或者使用curl.exe -v查看詳細(xì)請(qǐng)求過程。驗(yàn)證成功后按Ctrl C終止服務(wù)器。這里最容易犯的錯(cuò)誤是修改server.js后沒有重啟進(jìn)程。Node.js 不會(huì)自動(dòng)加載代碼修改必須結(jié)束舊進(jìn)程再啟動(dòng)。5. 讓開發(fā)更順手腳本、自動(dòng)重啟和調(diào)試5.1 package.json 的 scripts把啟動(dòng)命令寫進(jìn)package.json項(xiàng)目就會(huì)更規(guī)范{ name: node-first-app, version: 1.0.0, main: server.js, scripts: { start: node server.js, dev: nodemon server.js } }保存后執(zhí)行npm startnpm run dev需要先安裝 nodemon下面繼續(xù)講。5.2 使用 nodemon 自動(dòng)重啟開發(fā)時(shí)反復(fù)手動(dòng)停止、啟動(dòng)服務(wù)器很低效。可以用 nodemon 監(jiān)聽文件變化文件被保存時(shí)自動(dòng)重啟進(jìn)程npm install -D nodemon安裝后啟動(dòng)npx nodemon server.js這個(gè)依賴是開發(fā)依賴只有開發(fā)環(huán)境需要。打包或部署生產(chǎn)環(huán)境時(shí)不應(yīng)該依賴 nodemon而應(yīng)該使用進(jìn)程守護(hù)工具或容器管理。5.3 命令行調(diào)試與內(nèi)置調(diào)試器最簡單的故障定位方法是加日志const server http.createServer((req, res) { console.log(${req.method} ${req.url}); // ... });每來一個(gè)請(qǐng)求終端都會(huì)輸出請(qǐng)求方法和 URL。遇到瀏覽器請(qǐng)求/favicon.ico、請(qǐng)求路徑不對(duì)、參數(shù)丟失時(shí)日志是最快的證據(jù)。如果日志不夠可以使用 Node.js 內(nèi)置調(diào)試器node --inspect server.js然后打開 Chrome 的chrome://inspect對(duì) Node.js 進(jìn)程進(jìn)行斷點(diǎn)調(diào)試。不過這個(gè)操作對(duì)剛?cè)腴T的人可能略重先從日志排查更實(shí)際。5.4 通過日志和 curl 定位問題下面是一個(gè)簡單排查順序先看終端有沒有報(bào)錯(cuò)。沒有報(bào)錯(cuò)再用curl驗(yàn)證接口而不是只看瀏覽器。比較瀏覽器和curl的響應(yīng)差異定位請(qǐng)求方法、請(qǐng)求頭、請(qǐng)求參數(shù)問題。如果接口返回 404先打印req.url。如果接口返回亂碼檢查Content-Type是否帶charsetutf-8。如果請(qǐng)求一直超時(shí)檢查端口是否被占用、server.listen是否配置正確、防火墻是否攔截。6. 常見安裝和運(yùn)行問題排查6.1 Windows 安裝報(bào)錯(cuò)或缺少 Visual C Runtime在 Windows 安裝某些 Node.js 安裝包時(shí)可能輸出“需要 Microsoft Visual C 2015-2022 Redistributable”相關(guān)提示。這不是 Node.js 本身損壞而是操作系統(tǒng)缺少運(yùn)行庫。處理方式安裝微軟官方提供的 Visual C Redistributable 包。安裝完成后重啟電腦再重新安裝 Node.js。不要在同一個(gè)系統(tǒng)里反復(fù)安裝多個(gè).msi和.zip版 Node.js容易導(dǎo)致 PATH 混亂。6.2 輸入 node -v 提示不是內(nèi)部或外部命令常見原因有三個(gè)安裝完成后沒有新開終端窗口。安裝時(shí)沒有勾選“添加到 PATH”。系統(tǒng)存在舊版本殘留多條 PATH 互相干擾。排查方式where node echo %PATH%如果where node找到多個(gè)路徑通常說明舊版本或不同架構(gòu)的 Node.js 混在一起。建議先卸載所有不用的 Node.js只保留 nvm 管理的一個(gè)版本再重新配置 PATH。6.3 nvm install 提示 not yet released 或 not available使用 nvm 安裝具體版本時(shí)可能看到error installing 22.13.1: Node.js v22.13.1 is not yet released or is not available這通常有兩個(gè)原因nvm 本地的版本列表太舊還沒有同步到最新版本。你指定的版本號(hào)不正確或者該版本不在當(dāng)前 nvm 兼容列表中。處理方式nvm list available先查可用版本再選擇列表中存在的版本號(hào)安裝。如果列表里仍然沒有嘗試升級(jí) nvm-windows 到最新版本。不要憑感覺手寫版本號(hào)版本號(hào)必須和官方發(fā)布列表一致。6.4 npm install 很慢或超時(shí)優(yōu)先檢查 registrynpm config get registry如果地址是官方源導(dǎo)致速度慢按前面 3.2 節(jié)配置鏡像源。如果已經(jīng)是鏡像源仍然慢檢查是否項(xiàng)目依賴了非常多的大型包以及網(wǎng)絡(luò)是否不穩(wěn)定。不要頻繁刪除node_modules那不是解決慢的首選方法。6.5 端口被占用啟動(dòng)服務(wù)器時(shí)出現(xiàn)Error: listen EADDRINUSE: address already in use :::3000說明 3000 端口已經(jīng)被占用。查看占用進(jìn)程# Windows netstat -ano | findstr :3000 # Linux / macOS lsof -i :3000找到 PID 后確認(rèn)進(jìn)程可以結(jié)束再清理# Windows taskkill /PID 1234 /F也可以直接把server.js里的端口改成其他值比如3001。實(shí)際開發(fā)中端口應(yīng)該通過環(huán)境變量配置不寫死在代碼里。6.6 修改代碼后頁面沒變化Node.js 不會(huì)熱更新。如果修改了server.js但瀏覽器頁面還是舊內(nèi)容優(yōu)先確認(rèn)終端里是否重啟了服務(wù)器。如果使用 nodemon 卻仍然沒變化檢查正在執(zhí)行的是不是nodemon server.js以及文件保存位置是否在 nodemon 監(jiān)聽范圍內(nèi)。注意瀏覽器自帶緩存也會(huì)造成“代碼改了但頁面沒變”的假象。先用curl請(qǐng)求接口如果curl返回新內(nèi)容問題在瀏覽器緩存如果curl也返回舊內(nèi)容問題在服務(wù)進(jìn)程沒有重啟。7. 把第一個(gè) Web 應(yīng)用擴(kuò)展到接近生產(chǎn)形態(tài)7.1 使用 Express 重寫接口內(nèi)置http模塊適合理解原理但真實(shí)項(xiàng)目很少直接用它寫業(yè)務(wù)接口。更多項(xiàng)目會(huì)使用 Express。先安裝npm install express然后創(chuàng)建app.jsconst express require(express); const app express(); const port process.env.PORT || 3000; app.get(/, (req, res) { res.send(Hello Node.js Web App); }); app.get(/user, (req, res) { const name req.query.name || anonymous; res.json({ code: 0, data: { name, time: new Date().toISOString() } }); }); app.listen(port, () { console.log(Server running at http://127.0.0.1:${port}/); });Express 把路由、參數(shù)解析、JSON 響應(yīng)都封裝得更容易使用。學(xué)習(xí)和實(shí)際項(xiàng)目之間順序是先會(huì)用http模塊再切換到 Express最后再理解 Express 的中間件機(jī)制。7.2 環(huán)境變量與默認(rèn)值第一個(gè)應(yīng)用里端口寫死為3000這沒問題但生產(chǎn)環(huán)境通常不會(huì)固定端口。推薦方式const port process.env.PORT || 3000;這樣本地不配置時(shí)用 3000部署平臺(tái)注入PORT時(shí)讀取平臺(tái)端口。學(xué)習(xí)環(huán)境可以直接在命令行運(yùn)行。生產(chǎn)環(huán)境還要考慮日志寫到文件或集中日志平臺(tái)。進(jìn)程崩潰后自動(dòng)重啟。配置信息通過環(huán)境變量傳入。監(jiān)聽地址根據(jù)部署平臺(tái)調(diào)整。增加健康檢查接口。7.3 目錄規(guī)約和 .gitignore即使只有幾個(gè)文件也可以從一開始建立規(guī)范node-first-app/ ├── app.js ├── package.json ├── package-lock.json └── .gitignore.gitignore至少要忽略node_modules/ .env *.lognode_modules是依賴安裝后的目錄不應(yīng)該提交到 Git其他人拉取代碼后通過npm install恢復(fù)。7.4 學(xué)習(xí)環(huán)境與生產(chǎn)環(huán)境的差異維度學(xué)習(xí)環(huán)境生產(chǎn)環(huán)境啟動(dòng)方式node server.js或 nodemon進(jìn)程守護(hù)工具、容器、CI/CD 平臺(tái)端口寫死或process.env.PORT || 3000由平臺(tái)注入環(huán)境變量日志終端輸出獨(dú)立日志文件、日志收集系統(tǒng)異常處理res.end直接返回統(tǒng)一錯(cuò)誤中間件、告警依賴開發(fā)依賴不區(qū)分npm ci --production生成可復(fù)現(xiàn)依賴安全僅本機(jī)訪問鑒權(quán)、限流、HTTPS、防火墻策略這里最核心的理解是能跑通不代表能上線。生產(chǎn)環(huán)境多出來的不是“更多代碼”而是對(duì)異常、可觀測性、回滾和安全的約束。7.5 可復(fù)用的檢查清單分享一份適合自己的項(xiàng)目發(fā)布前檢查清單node -v與項(xiàng)目要求的 Node.js 版本一致。package.json的scripts.start能正常啟動(dòng)。接口使用curl -i驗(yàn)證過狀態(tài)碼、響應(yīng)頭和響應(yīng)體。node_modules已加入.gitignore。端口沒有寫死支持process.env.PORT。異常分支有日志不會(huì)靜默失敗。不使用裸catch吞掉錯(cuò)誤。不需要在終端手工維持進(jìn)程時(shí)提供進(jìn)程守護(hù)方案。對(duì)于剛完成第一個(gè) Web 應(yīng)用的開發(fā)者下一步可以按這個(gè)順序擴(kuò)展先給接口增加表單提交和 JSON 請(qǐng)求體解析然后加上簡單的文件讀寫接著學(xué)習(xí) Express 中間件再接觸數(shù)據(jù)庫連接和 ORM。每一步都保持“先起一個(gè)能跑的最小例子再逐步加功能”比一次性啃完 Node.js 所有 API 有效得多。 Node.js入門指南：從環(huán)境安裝到構(gòu)建第一個(gè)Web應(yīng)用
Node.js 入門教程很多但真正能幫你在 1 小時(shí)內(nèi)把安裝、驗(yàn)證、編碼、跑通全部走完的并不多。這篇文章以“從下載 Node.js 到寫出第一個(gè) Web 應(yīng)用”為主線把 60 分鐘拆成四段前 10 分鐘搞清楚 Node.js 是干什么的、版本怎么選中間 15 分鐘完成安裝和 npm 基礎(chǔ)配置接下來 20 分鐘用 Node.js 自帶模塊寫一個(gè)能訪問的 Web 頁面最后 15 分鐘排查安裝和運(yùn)行時(shí)最常見的報(bào)錯(cuò)。這樣做的好處是每一步都能驗(yàn)證結(jié)果不會(huì)出現(xiàn)“環(huán)境配了一下午代碼一跑全是問題”的情況。1. 先搞清楚 Node.js 是干什么的再?zèng)Q定安裝哪個(gè)版本1.1 Node.js 不是普通腳本工具而是一個(gè) JavaScript 運(yùn)行時(shí)Node.js 的官方定位是“基于 Chrome V8 引擎的 JavaScript 運(yùn)行時(shí)”。通俗一點(diǎn)說瀏覽器給 JavaScript 提供了window、document、fetch等環(huán)境而 Node.js 給 JavaScript 提供了文件讀取、網(wǎng)絡(luò)請(qǐng)求、進(jìn)程管理、操作系統(tǒng)交互等能力。這意味著你不再需要通過 HTML 頁面來運(yùn)行 JavaScript可以直接在終端執(zhí)行node -e console.log(hello node)這行命令會(huì)創(chuàng)建一個(gè) Node.js 進(jìn)程執(zhí)行字符串里的 JavaScript 代碼然后把結(jié)果輸出到控制臺(tái)。對(duì)剛?cè)腴T的人來說只要理解這一點(diǎn)就夠了Node.js 讓 JavaScript 從“只能操作頁面”變成“可以操作文件和網(wǎng)絡(luò)”的通用語言。1.2 事件驅(qū)動(dòng)、非阻塞 I/O 到底影響什么很多資料會(huì)提到“事件驅(qū)動(dòng)”“非阻塞 I/O”“單線程”。這里用一句更貼近實(shí)際的話解釋Node.js 遇到耗時(shí)操作時(shí)不會(huì)一直卡住等待結(jié)果而是先繼續(xù)處理其他請(qǐng)求等耗時(shí)操作完成后通過回調(diào)繼續(xù)處理?？匆粋€(gè)簡單對(duì)比// 模擬耗時(shí)讀取不推薦生產(chǎn)環(huán)境使用 fs.readFileSync const fs require(fs); console.log(1. 開始讀取); const data fs.readFileSync(example.txt, utf8); console.log(2. 讀取完成, data.length); console.log(3. 繼續(xù)執(zhí)行);上面這段用同步方式讀文件執(zhí)行到第二行時(shí)整個(gè)進(jìn)程會(huì)等待文件讀完才繼續(xù)執(zhí)行第三行。如果改用異步方式const fs require(fs); console.log(1. 開始讀取); fs.readFile(example.txt, utf8, (err, data) { console.log(2. 讀取完成, data ? data.length : error); }); console.log(3. 繼續(xù)執(zhí)行);執(zhí)行順序會(huì)變成“1、3、2”。異步 I/O 是 Node.js 能同時(shí)處理大量并發(fā)請(qǐng)求的重要原因。對(duì)于剛?cè)腴T的第一個(gè) Web 應(yīng)用你不需要立刻精通它但必須理解fs.readFile的回調(diào)不會(huì)阻塞后續(xù)代碼。1.3 LTS、Current、偶數(shù)版本號(hào)怎么選安裝 Node.js 前最容易出錯(cuò)的是版本選擇。官方發(fā)布版本大致分兩類版本類型說明適合場景LTSLong Term Support長期支持版本會(huì)持續(xù)維護(hù)和修復(fù)漏洞推薦新手、生產(chǎn)環(huán)境、企業(yè)項(xiàng)目Current當(dāng)前版本包含新特性但迭代快、可能不穩(wěn)定嘗鮮、特性驗(yàn)證、短期學(xué)習(xí)偶數(shù)版本例如 18、20、22通常更容易進(jìn)入 LTS 周期穩(wěn)定性優(yōu)先的項(xiàng)目奇數(shù)版本例如 19、21、23通常是過渡版本不建議作為主力實(shí)際項(xiàng)目里建議安裝當(dāng)前最新 LTS而不是最新 Current。原因很直接很多 npm 包對(duì) Node.js 版本有要求LTS 版本生態(tài)兼容更好遇到問題時(shí)搜索引擎能找到更多答案。1.4 安裝前的環(huán)境檢查清單安裝前先檢查操作系統(tǒng)、CPU 架構(gòu)和是否已存在舊版本# Windows PowerShell systeminfo | findstr /C:OS # Linux / macOS uname -m # 檢查是否已經(jīng)安裝過 Node.js node -v npm -vWindows 下尤其要注意架構(gòu)絕大多數(shù)現(xiàn)代電腦使用 64 位系統(tǒng)應(yīng)該下載x64安裝包部分舊電腦是 32 位系統(tǒng)需要下載x86包。如果系統(tǒng)里已經(jīng)安裝了舊版 Node.js先確認(rèn)版本避免安裝新版本后 PATH 環(huán)境變量混亂。2. 安裝 Node.js 的三種方式以及為什么推薦用 nvm2.1 Windows 圖形化安裝包最快但最不靈活進(jìn)入 Node.js 官網(wǎng)下載頁選擇適合當(dāng)前系統(tǒng)的.msi安裝包雙擊運(yùn)行即可。安裝過程中默認(rèn)已經(jīng)包含“添加到 PATH”選項(xiàng)一般不需要修改一直下一步即可。安裝完成后重新打開一個(gè)終端窗口執(zhí)行node -v npm -v如果輸出類似v22.13.1 10.9.2說明安裝成功。需要注意安裝完成后必須新開終端窗口否則當(dāng)前終端的 PATH 不會(huì)刷新仍然提示找不到node命令。這種方式適合只跑一次 Node.js、不打算切換項(xiàng)目的用戶。缺點(diǎn)是當(dāng)某個(gè)項(xiàng)目依賴 Node.js 20另一個(gè)項(xiàng)目依賴 Node.js 22 時(shí)圖形化安裝包無法靈活切換版本。2.2 Windows 下使用 nvm-windows 管理多版本跨項(xiàng)目開發(fā)時(shí)推薦使用 nvmNode Version Manager管理 Node.js 版本。Windows 上沒有直接移植原版 nvm常用的是 nvm-windows。安裝方式從 nvm-windows 的發(fā)布頁面下載安裝包。安裝到一個(gè)不含中文和空格的目錄例如C:\nvm。安裝完成后終端執(zhí)行nvm version然后安裝并切換 Node.js 版本nvm install 22.13.1 nvm use 22.13.1 node -v執(zhí)行nvm use后node命令會(huì)指向 nvm 管理目錄下的對(duì)應(yīng)版本。這里的關(guān)鍵點(diǎn)是不要直接到官網(wǎng)下載安裝包和管理器混用那會(huì)讓node命令的來源不確定。我的建議是Windows 新項(xiàng)目統(tǒng)一用 nvm-windows即使以后需要升級(jí) Node.js 或同時(shí)維護(hù)舊項(xiàng)目也不會(huì)被版本問題卡住。2.3 macOS/Linux 下的 nvm 安裝macOS 或 Linux 用戶可以使用官方腳本安裝 nvm但不要直接復(fù)制網(wǎng)上來路不明的curl腳本應(yīng)該先檢查內(nèi)容再執(zhí)行。安裝 nvm 后shell 配置文件通常是.zshrc或.bashrc會(huì)追加 nvm 初始化腳本。安裝完成要重新加載配置source ~/.zshrc然后安裝 Node.jsnvm install --lts nvm use --lts node -v--lts會(huì)安裝當(dāng)前最新的長期支持版本避免手動(dòng)指定容易過時(shí)的版本號(hào)。2.4 安裝完成后的檢查點(diǎn)無論使用哪種方式都要完成以下檢查檢查項(xiàng)命令預(yù)期結(jié)果Node.js 可用node -v輸出類似v22.13.1npm 可用npm -v輸出類似10.9.2nvm 可用nvm version輸出 nvm 版本號(hào)全局路徑npm root -g輸出存在的全局 node_modules 目錄緩存路徑npm config get cache輸出 npm 緩存目錄如果node -v能正常輸出但npm -v報(bào)錯(cuò)通常是因?yàn)榘惭b包損壞、PATH 中存在多個(gè) Node.js 目錄或舊版殘留。不要急著重裝先運(yùn)行where nodeWindows或which nodeLinux/macOS確認(rèn)實(shí)際執(zhí)行路徑。3. 用 npm 做基礎(chǔ)配置鏡像源、全局路徑和緩存目錄3.1 npm 的職責(zé)與版本npm 是 Node.js 自帶的包管理器負(fù)責(zé)下載、安裝、卸載第三方依賴并維護(hù)項(xiàng)目的依賴關(guān)系。它和node是兩套程序Node.js 負(fù)責(zé)運(yùn)行 JavaScriptnpm 負(fù)責(zé)管理 JavaScript 需要的庫。npm 的版本通常不等同于 Node.js 版本。安裝 Node.js 后npm 也一并安裝。日常使用中不要只關(guān)注node -v還要關(guān)注npm -v。某些 CLI 工具會(huì)要求 npm 版本達(dá)到閾值如果版本過舊可以通過以下命令升級(jí) npmnpm install -g npmlatest3.2 配置鏡像源避免安裝依賴超時(shí)在實(shí)際網(wǎng)絡(luò)環(huán)境里直接從官方源安裝依賴可能很慢常見表現(xiàn)是npm install長時(shí)間停留在idealTree階段或者直接超時(shí)?？梢园?npm 的 registry 切換到國內(nèi)鏡像npm config set registry https://registry.npmmirror.com/驗(yàn)證是否生效npm config get registry也可以直接查看配置文件位置npm config ls -l這里要注意的是全局使用鏡像源會(huì)影響所有項(xiàng)目。如果某些項(xiàng)目必須使用官方源或公司內(nèi)網(wǎng)源可以只在項(xiàng)目根目錄創(chuàng)建.npmrc寫入registryhttps://registry.npmjs.org/項(xiàng)目級(jí)配置會(huì)覆蓋全局配置。這樣就能做到“全局用鏡像個(gè)別項(xiàng)目用官方源”。3.3 全局安裝路徑和權(quán)限使用全局安裝命令時(shí)npm install -g npm-check-updates全局包會(huì)安裝到npm root -g指向的目錄。Windows 下全局命令通常會(huì)被軟鏈到 npm 前綴目錄如果沒有正確配置會(huì)出現(xiàn)“命令安裝成功但終端找不到”的問題。Linux/macOS 下如果直接使用npm install -g遇到權(quán)限錯(cuò)誤不要用sudo強(qiáng)行安裝更推薦修改 npm 的全局目錄到用戶目錄下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后在 shell 配置文件中添加export PATH~/.npm-global/bin:$PATH這樣全局安裝的 CLI 工具都可以直接用也避免了權(quán)限污染。3.4 驗(yàn)證 npm 配置配置完成后創(chuàng)建一個(gè)臨時(shí)目錄測試 npm 是否能正常安裝依賴mkdir npm-config-test cd npm-config-test npm init -y npm install lodash看到node_modules目錄生成并出現(xiàn)package-lock.json說明安裝鏈路正常。檢查點(diǎn)有npm config get registry輸出鏡像地址。npm root -g輸出一個(gè)可寫目錄。npm install沒有權(quán)限和超時(shí)報(bào)錯(cuò)。注意不要在生產(chǎn)環(huán)境隨意使用npm cache clean --force。多數(shù)安裝問題不是緩存損壞而是鏡像源或版本不對(duì)。強(qiáng)行清理緩存反而會(huì)拖慢下一次安裝。4. 創(chuàng)建第一個(gè) Web 應(yīng)用使用內(nèi)置 http 模塊4.1 初始化項(xiàng)目和目錄結(jié)構(gòu)先創(chuàng)建項(xiàng)目目錄mkdir node-first-app cd node-first-app npm init -ynpm init -y會(huì)生成一個(gè)默認(rèn)的package.json內(nèi)容類似于{ name: node-first-app, version: 1.0.0, description: , main: index.js, scripts: { test: echo \Error: no test specified\ exit 1 } }對(duì)于第一個(gè) Web 應(yīng)用這個(gè)文件不是必須修改的但要理解它記錄了三類信息項(xiàng)目名稱與版本、入口文件、啟動(dòng)腳本。后續(xù)添加第三方依賴時(shí)dependencies也會(huì)寫到這里。4.2 最小可運(yùn)行的 HTTP 服務(wù)器新建server.js文件寫入const http require(http); const hostname 127.0.0.1; const port 3000; const server http.createServer((req, res) { res.statusCode 200; res.setHeader(Content-Type, text/plain; charsetutf-8); res.end(Hello Node.js Web App); }); server.listen(port, hostname, () { console.log(Server running at http://${hostname}:${port}/); });這段代碼的每一行都有明確作用require(http)導(dǎo)入 Node.js 內(nèi)置的 HTTP 模塊。http.createServer接收一個(gè)回調(diào)函數(shù)每次有請(qǐng)求進(jìn)來都會(huì)執(zhí)行。req是請(qǐng)求對(duì)象包含 URL、請(qǐng)求方法、請(qǐng)求頭。res是響應(yīng)對(duì)象用來設(shè)置狀態(tài)碼、響應(yīng)頭和響應(yīng)體。listening是網(wǎng)絡(luò)層面的監(jiān)聽端口這里指定127.0.0.1:3000。4.3 解析請(qǐng)求參數(shù)和返回 JSON第一個(gè) Web 應(yīng)用如果只有“Hello World”還看不出實(shí)用價(jià)值。擴(kuò)展一下根據(jù) URL 返回用戶信息。const http require(http); const url require(url); const server http.createServer((req, res) { const parsedUrl new URL(req.url, http://${req.headers.host}); const pathname parsedUrl.pathname; res.setHeader(Content-Type, application/json; charsetutf-8); if (req.method GET pathname /user) { const name parsedUrl.searchParams.get(name) || anonymous; res.statusCode 200; res.end( JSON.stringify({ code: 0, data: { name, time: new Date().toISOString() } }) ); return; } res.statusCode 404; res.end(JSON.stringify({ code: 404, message: Not Found })); }); server.listen(3000, 127.0.0.1, () { console.log(Server running at http://127.0.0.1:3000/); });訪問http://127.0.0.1:3000/user?namenode返回{code:0,data:{name:node,time:2025-01-01T12:00:00.000Z}}這里用到了URL對(duì)象是 Node.js 內(nèi)置的 URL 解析方式。比手動(dòng)拆分字符串更可靠也能處理中文參數(shù)、編碼問題。4.4 啟動(dòng)服務(wù)和驗(yàn)證接口執(zhí)行node server.js輸出Server running at http://127.0.0.1:3000/然后打開瀏覽器訪問http://127.0.0.1:3000/user?namenode或者用命令行驗(yàn)證curl http://127.0.0.1:3000/user?namenode注意curl在 Windows PowerShell 中默認(rèn)可能是Invoke-WebRequest的別名。如果輸出格式不同可以改用curl.exe或者使用curl.exe -v查看詳細(xì)請(qǐng)求過程。驗(yàn)證成功后按Ctrl C終止服務(wù)器。這里最容易犯的錯(cuò)誤是修改server.js后沒有重啟進(jìn)程。Node.js 不會(huì)自動(dòng)加載代碼修改必須結(jié)束舊進(jìn)程再啟動(dòng)。5. 讓開發(fā)更順手腳本、自動(dòng)重啟和調(diào)試5.1 package.json 的 scripts把啟動(dòng)命令寫進(jìn)package.json項(xiàng)目就會(huì)更規(guī)范{ name: node-first-app, version: 1.0.0, main: server.js, scripts: { start: node server.js, dev: nodemon server.js } }保存后執(zhí)行npm startnpm run dev需要先安裝 nodemon下面繼續(xù)講。5.2 使用 nodemon 自動(dòng)重啟開發(fā)時(shí)反復(fù)手動(dòng)停止、啟動(dòng)服務(wù)器很低效。可以用 nodemon 監(jiān)聽文件變化文件被保存時(shí)自動(dòng)重啟進(jìn)程npm install -D nodemon安裝后啟動(dòng)npx nodemon server.js這個(gè)依賴是開發(fā)依賴只有開發(fā)環(huán)境需要。打包或部署生產(chǎn)環(huán)境時(shí)不應(yīng)該依賴 nodemon而應(yīng)該使用進(jìn)程守護(hù)工具或容器管理。5.3 命令行調(diào)試與內(nèi)置調(diào)試器最簡單的故障定位方法是加日志const server http.createServer((req, res) { console.log(${req.method} ${req.url}); // ... });每來一個(gè)請(qǐng)求終端都會(huì)輸出請(qǐng)求方法和 URL。遇到瀏覽器請(qǐng)求/favicon.ico、請(qǐng)求路徑不對(duì)、參數(shù)丟失時(shí)日志是最快的證據(jù)。如果日志不夠可以使用 Node.js 內(nèi)置調(diào)試器node --inspect server.js然后打開 Chrome 的chrome://inspect對(duì) Node.js 進(jìn)程進(jìn)行斷點(diǎn)調(diào)試。不過這個(gè)操作對(duì)剛?cè)腴T的人可能略重先從日志排查更實(shí)際。5.4 通過日志和 curl 定位問題下面是一個(gè)簡單排查順序先看終端有沒有報(bào)錯(cuò)。沒有報(bào)錯(cuò)再用curl驗(yàn)證接口而不是只看瀏覽器。比較瀏覽器和curl的響應(yīng)差異定位請(qǐng)求方法、請(qǐng)求頭、請(qǐng)求參數(shù)問題。如果接口返回 404先打印req.url。如果接口返回亂碼檢查Content-Type是否帶charsetutf-8。如果請(qǐng)求一直超時(shí)檢查端口是否被占用、server.listen是否配置正確、防火墻是否攔截。6. 常見安裝和運(yùn)行問題排查6.1 Windows 安裝報(bào)錯(cuò)或缺少 Visual C Runtime在 Windows 安裝某些 Node.js 安裝包時(shí)可能輸出“需要 Microsoft Visual C 2015-2022 Redistributable”相關(guān)提示。這不是 Node.js 本身損壞而是操作系統(tǒng)缺少運(yùn)行庫。處理方式安裝微軟官方提供的 Visual C Redistributable 包。安裝完成后重啟電腦再重新安裝 Node.js。不要在同一個(gè)系統(tǒng)里反復(fù)安裝多個(gè).msi和.zip版 Node.js容易導(dǎo)致 PATH 混亂。6.2 輸入 node -v 提示不是內(nèi)部或外部命令常見原因有三個(gè)安裝完成后沒有新開終端窗口。安裝時(shí)沒有勾選“添加到 PATH”。系統(tǒng)存在舊版本殘留多條 PATH 互相干擾。排查方式where node echo %PATH%如果where node找到多個(gè)路徑通常說明舊版本或不同架構(gòu)的 Node.js 混在一起。建議先卸載所有不用的 Node.js只保留 nvm 管理的一個(gè)版本再重新配置 PATH。6.3 nvm install 提示 not yet released 或 not available使用 nvm 安裝具體版本時(shí)可能看到error installing 22.13.1: Node.js v22.13.1 is not yet released or is not available這通常有兩個(gè)原因nvm 本地的版本列表太舊還沒有同步到最新版本。你指定的版本號(hào)不正確或者該版本不在當(dāng)前 nvm 兼容列表中。處理方式nvm list available先查可用版本再選擇列表中存在的版本號(hào)安裝。如果列表里仍然沒有嘗試升級(jí) nvm-windows 到最新版本。不要憑感覺手寫版本號(hào)版本號(hào)必須和官方發(fā)布列表一致。6.4 npm install 很慢或超時(shí)優(yōu)先檢查 registrynpm config get registry如果地址是官方源導(dǎo)致速度慢按前面 3.2 節(jié)配置鏡像源。如果已經(jīng)是鏡像源仍然慢檢查是否項(xiàng)目依賴了非常多的大型包以及網(wǎng)絡(luò)是否不穩(wěn)定。不要頻繁刪除node_modules那不是解決慢的首選方法。6.5 端口被占用啟動(dòng)服務(wù)器時(shí)出現(xiàn)Error: listen EADDRINUSE: address already in use :::3000說明 3000 端口已經(jīng)被占用。查看占用進(jìn)程# Windows netstat -ano | findstr :3000 # Linux / macOS lsof -i :3000找到 PID 后確認(rèn)進(jìn)程可以結(jié)束再清理# Windows taskkill /PID 1234 /F也可以直接把server.js里的端口改成其他值比如3001。實(shí)際開發(fā)中端口應(yīng)該通過環(huán)境變量配置不寫死在代碼里。6.6 修改代碼后頁面沒變化Node.js 不會(huì)熱更新。如果修改了server.js但瀏覽器頁面還是舊內(nèi)容優(yōu)先確認(rèn)終端里是否重啟了服務(wù)器。如果使用 nodemon 卻仍然沒變化檢查正在執(zhí)行的是不是nodemon server.js以及文件保存位置是否在 nodemon 監(jiān)聽范圍內(nèi)。注意瀏覽器自帶緩存也會(huì)造成“代碼改了但頁面沒變”的假象。先用curl請(qǐng)求接口如果curl返回新內(nèi)容問題在瀏覽器緩存如果curl也返回舊內(nèi)容問題在服務(wù)進(jìn)程沒有重啟。7. 把第一個(gè) Web 應(yīng)用擴(kuò)展到接近生產(chǎn)形態(tài)7.1 使用 Express 重寫接口內(nèi)置http模塊適合理解原理但真實(shí)項(xiàng)目很少直接用它寫業(yè)務(wù)接口。更多項(xiàng)目會(huì)使用 Express。先安裝npm install express然后創(chuàng)建app.jsconst express require(express); const app express(); const port process.env.PORT || 3000; app.get(/, (req, res) { res.send(Hello Node.js Web App); }); app.get(/user, (req, res) { const name req.query.name || anonymous; res.json({ code: 0, data: { name, time: new Date().toISOString() } }); }); app.listen(port, () { console.log(Server running at http://127.0.0.1:${port}/); });Express 把路由、參數(shù)解析、JSON 響應(yīng)都封裝得更容易使用。學(xué)習(xí)和實(shí)際項(xiàng)目之間順序是先會(huì)用http模塊再切換到 Express最后再理解 Express 的中間件機(jī)制。7.2 環(huán)境變量與默認(rèn)值第一個(gè)應(yīng)用里端口寫死為3000這沒問題但生產(chǎn)環(huán)境通常不會(huì)固定端口。推薦方式const port process.env.PORT || 3000;這樣本地不配置時(shí)用 3000部署平臺(tái)注入PORT時(shí)讀取平臺(tái)端口。學(xué)習(xí)環(huán)境可以直接在命令行運(yùn)行。生產(chǎn)環(huán)境還要考慮日志寫到文件或集中日志平臺(tái)。進(jìn)程崩潰后自動(dòng)重啟。配置信息通過環(huán)境變量傳入。監(jiān)聽地址根據(jù)部署平臺(tái)調(diào)整。增加健康檢查接口。7.3 目錄規(guī)約和 .gitignore即使只有幾個(gè)文件也可以從一開始建立規(guī)范node-first-app/ ├── app.js ├── package.json ├── package-lock.json └── .gitignore.gitignore至少要忽略node_modules/ .env *.lognode_modules是依賴安裝后的目錄不應(yīng)該提交到 Git其他人拉取代碼后通過npm install恢復(fù)。7.4 學(xué)習(xí)環(huán)境與生產(chǎn)環(huán)境的差異維度學(xué)習(xí)環(huán)境生產(chǎn)環(huán)境啟動(dòng)方式node server.js或 nodemon進(jìn)程守護(hù)工具、容器、CI/CD 平臺(tái)端口寫死或process.env.PORT || 3000由平臺(tái)注入環(huán)境變量日志終端輸出獨(dú)立日志文件、日志收集系統(tǒng)異常處理res.end直接返回統(tǒng)一錯(cuò)誤中間件、告警依賴開發(fā)依賴不區(qū)分npm ci --production生成可復(fù)現(xiàn)依賴安全僅本機(jī)訪問鑒權(quán)、限流、HTTPS、防火墻策略這里最核心的理解是能跑通不代表能上線。生產(chǎn)環(huán)境多出來的不是“更多代碼”而是對(duì)異常、可觀測性、回滾和安全的約束。7.5 可復(fù)用的檢查清單分享一份適合自己的項(xiàng)目發(fā)布前檢查清單node -v與項(xiàng)目要求的 Node.js 版本一致。package.json的scripts.start能正常啟動(dòng)。接口使用curl -i驗(yàn)證過狀態(tài)碼、響應(yīng)頭和響應(yīng)體。node_modules已加入.gitignore。端口沒有寫死支持process.env.PORT。異常分支有日志不會(huì)靜默失敗。不使用裸catch吞掉錯(cuò)誤。不需要在終端手工維持進(jìn)程時(shí)提供進(jìn)程守護(hù)方案。對(duì)于剛完成第一個(gè) Web 應(yīng)用的開發(fā)者下一步可以按這個(gè)順序擴(kuò)展先給接口增加表單提交和 JSON 請(qǐng)求體解析然后加上簡單的文件讀寫接著學(xué)習(xí) Express 中間件再接觸數(shù)據(jù)庫連接和 ORM。每一步都保持“先起一個(gè)能跑的最小例子再逐步加功能”比一次性啃完 Node.js 所有 API 有效得多。