Showing Posts From

Node.js

Soulock
2026年06月20日
- 工具分享

NVM 环境配置与 npm 找不到的排查

macOS / Linux 上配 nvm 先确认 nvm 安装位置： echo $NVM_DIR通常是 ~/.nvm。在 ~/.zshrc（zsh）或 ~/.bashrc（bash）末尾加： export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"生效并验证： source ~/.zshrc nvm -vWindows 上配 nvm-windows 先看 nvm 目录： nvm root通常输出： C:\Users\<你>\AppData\Roaming\nvm系统环境变量里加两条： NVM_HOME = C:\Users\<你>\AppData\Roaming\nvm NVM_SYMLINK = C:\Program Files\nodejs再把 Path 里追加： %NVM_HOME% %NVM_SYMLINK%新开一个 CMD 窗口，验证： nvm version node -v npm -v常用命令速查 nvm install 22 # 装 Node 22 nvm list # 已装版本 nvm use 22 # 切换版本 nvm alias default 22 # 设默认（macOS/Linux） nvm current # 当前使用版本which node 有输出，但 npm not found 碰到这种情况： $ which node /Users/you/.nvm/versions/node/v22.21.1/bin/node$ which npm npm not found有六种可能，从概率高到低排： 1. 只装了 nvm 没装 Node nvm list # 一片空 nvm install 22 nvm use 222. 版本没激活 nvm current # 显示 none / N/A nvm use 223. PATH 没指向当前 Node echo $PATH # 看有没有 .nvm/versions/node/v22.x.x/bin4. Node 目录里 npm 文件真的没了 ls -lah /Users/you/.nvm/versions/node/v22.21.1/bin/正常应该有 node、npm、npx、corepack。只有 node 说明安装被中断过，重装： nvm uninstall 22 nvm install 225. Windows：nvm-windows 软链坏了（最常见） dir "C:\Program Files\nodejs"看到目录是空的或者链接指向失效版本，重新 nvm use： nvm use 22.19.0之后 where node / where npm 都会有结果。 6. Homebrew 装的 nvm 没加载环境 nvm use default # 或 nvm install --lts一句话总结 nvm 有问题时按这个顺序自检：nvm list → nvm current → which node / which npm → 检查 bin 目录是否完整。95% 的问题都是"没 use 版本"或"软链坏了"。

Soulock
2026年06月16日
- 工具分享

npm cb() never called 别再瞎清缓存：先看 Node 和 npm 匹不匹配

老项目上手，npm install 直接崩： npm ERR! cb() never called!npm ERR! This is an error with npm itself. Please report this error at: npm ERR! <https://npm.community>网上一搜全是"清缓存、删 node_modules、换镜像"这种模板答案。真去清了，然后再跑就变成： ERROR: npm v11.17.0 is known not to run on Node.js v14.21.3. This version of npm supports the following node versions: `^20.17.0 || >=22.9.0`SyntaxError: Unexpected token '&&='这才是真面目——Node 版本和 npm 版本对不上。症状识别看到这两种就是版本冲突：cb() never called（npm 内部逻辑走到不该走的分支） SyntaxError: Unexpected token （npm 用了新语法，老 Node 不认识，比如 &&= 是 Node 15+ 才有的）不是包坏了、不是 registry 挂了、也不是缓存的锅。 Node 与 npm 的兼容表Node 版本兼容的 npmNode 14 npm 6 ~ 8Node 16 npm 7 ~ 8Node 18 npm 9 ~ 10Node 20 npm 10 ~ 11Node 22 npm 10 ~ 11跨太多档就会互相不认。npm 11 明确要求 Node >= 20.17 或 >= 22.9。正确修法方案一：直接升 Node（推荐）用 nvm： nvm install 22 nvm use 22 nvm alias default 22 node -v npm -vNode 22 + npm 10/11，是现在最省事的组合。方案二：必须用老 Node，就降 npm 比如项目锁死 Node 14： npm install -g npm@6 # 或 npm install -g npm@8但注意——大部分现代依赖已经放弃了 Node 14，长远还是得升。方案三：项目里锁定引擎（推荐） package.json 里加： { "engines": { "node": ">=20.17" } }结合 nvm use 和 .nvmrc： echo "22" > .nvmrc nvm use # 自动读 .nvmrc新人 clone 下来 nvm use 就切对了。如果只是普通 cb() never called Node/npm 版本没问题，仍然报的情况下才走"缓存派"步骤： npm cache clean --force rm -rf node_modules package-lock.json npm install --legacy-peer-deps顺带换个镜像加速： npm config set registry https://registry.npmmirror.com一句话总结看到 cb() never called 别急着删 node_modules，先 node -v && npm -v 对一下兼容表。绝大多数是 Node 版本跟不上 npm。

Soulock
2026年05月22日
- Linux

Node 报 GLIBC_2.38 not found 的根因和四种解法

宝塔服务器启动 Node 项目，直接崩： Error: /lib64/libm.so.6: version `GLIBC_2.38' not found (required by /www/wwwroot/yourproject/server/node_modules/sqlite3/build/Release/node_sqlite3.node) code: 'ERR_DLOPEN_FAILED'这是典型的 glibc 版本不匹配。sqlite3.node 是个 native 二进制，编译时链接的 glibc 是 2.38，服务器 glibc 只有 2.17 或 2.28，加载不了。先确认服务器 glibc 版本 ldd --versionCentOS 7 通常是 2.17，Rocky 8 / 老 Ubuntu 是 2.28。而 Ubuntu 24 / Debian 13 的 glibc 已经到 2.38+，本地编译的东西拿过去自然跑不动。场景还原 99% 是这么造成的：本地新系统 npm install 打包整个项目（包括 node_modules）上传到服务器服务器上直接 node index.js 崩node_modules/sqlite3/build/Release/node_sqlite3.node 是在本机 Ubuntu 24 编译的，扔到 CentOS 7 上当然报 GLIBC。四种解法方案一：服务器重新编译（推荐） cd /www/wwwroot/yourproject/server rm -rf node_modules package-lock.json npm install或者只重编译原生模块： npm rebuild sqlite3编译失败通常是缺工具链： # CentOS / RHEL yum groupinstall "Development Tools" -y yum install python3 gcc gcc-c++ make -y# Ubuntu / Debian apt install build-essential python3 make g++ -y方案二：本地别上传 node_modules 正确的部署流程：本地只上传 package.json + package-lock.json 服务器 npm install.gitignore 里加上 node_modules/，部署脚本里 rsync --exclude=node_modules/，这类问题就彻底没了。方案三：换更省心的 SQLite 驱动老牌 sqlite3 依赖 node-gyp 编译，每次升 Node 都可能炸。换成：better-sqlite3（同步 API、性能更好） libsql（Cloudflare 生态）npm install better-sqlite3大多数场景 API 迁移不复杂，还能避开 native 编译地狱。方案四：升级系统 glibc（不推荐） CentOS 7 手动装高版本 glibc 有极高概率把系统弄崩，别碰。要新 glibc 就直接升系统或者上 Docker——用官方 Node 镜像编译，产物就是那个环境的 glibc。一条经验 Node 项目部署，永远不要把 node_modules 传上服务器。让服务器自己 npm install，很多 native 模块问题从此消失。

Soulock
2026年05月13日
- 技术

Node 内置 SQLite 报 statement has been finalized 的原因

Node 22 开始有了内置的 node:sqlite，同步 API 用起来非常顺。但启动时挂： ExperimentalWarning: SQLite is an experimental feature Failed to start server Error: statement has been finalized at readDeviceStates (src/lib/database.ts:76:38) ... code: 'ERR_INVALID_STATE'这个错的字面意思很明确：你在一个已经 finalize() 过的 prepared statement 上继续调用 all() / get() / iterate()。三种最常见的成因 1. 手动过早 finalize const stmt = db.prepare("SELECT * FROM devices"); try { return stmt.all(); } finally { stmt.finalize(); }看上去正确。但如果 stmt.all() 返回的是迭代器（iterate()）而不是数组（all()），外层还在懒消费，finalize 一走就崩。用 all() 拿到具体数组的写法没这个问题。 2. 用了 using 自动 finalize（Node 22 的新语法） export function readDeviceStates() { using stmt = db.prepare("SELECT * FROM device_states"); return stmt.iterate(); // ← 迭代器，出了作用域 stmt 就被 finalize 了 }using 借用了 TC39 的 Explicit Resource Management 提案，出作用域时会自动调 [Symbol.dispose]()，也就是 finalize()。返回迭代器给外部继续用，外部一 next() 就炸。规则：using + iterate() 不能混，要么用 all() 一次拿全部再返回，要么调用方也 using。 3. 模块级缓存了 stmt // 模块顶部 const readStmt = db.prepare("SELECT * FROM device_states");export function readDeviceStates() { return readStmt.all(); }看着挺合理——避免每次 prepare 的开销。但代码其它地方可能：单元测试用 db.close() 关掉了数据库（stmt 一起 finalize）有热重载/HMR 重新 import 了模块（旧 stmt 引用还留着）显式调用了 readStmt.finalize() 想清理，然后忘了之后再走这个函数就 ERR_INVALID_STATE。推荐写法每次现 prepare，让 GC 管理： export function readDeviceStates() { const stmt = db.prepare("SELECT * FROM device_states"); return stmt.all(); // 立刻取完，不返回 iterator }现代 SQLite 的 prepare 开销很小，不需要为性能提前优化。要缓存的话，配套复用而不是复用 + finalize： const cache = new Map<string, ReturnType<typeof db.prepare>>();function s(sql: string) { let stmt = cache.get(sql); if (!stmt) { stmt = db.prepare(sql); cache.set(sql, stmt); } return stmt; }// 用： s("SELECT * FROM device_states").all();不在缓存生命周期外手动 finalize。数据库 close 时统一 cache.clear()。要用 using 就一次性拿完数据： export function readDeviceStates() { using stmt = db.prepare("SELECT * FROM device_states"); return stmt.all(); // 数组，可以安全跨作用域 }一句话总结 statement has been finalized = 你正在用一个死掉的 stmt。别返回迭代器给作用域外、别在模块级缓存又手动 finalize。改成"每次 prepare + all()"最省心。

Soulock
2026年05月10日
- 前端

SyntaxError: Unexpected identifier '目'：文本被贴进 JS 文件

看到这个报错，几乎不用想：题目 AI辅助的全方位科研管理与创作平台 ^ SyntaxError: Unexpected identifier '目' at wrapSafe (node:internal/modules/cjs/loader:1637:18)Node 把这一行当代码解析了，而中文字符不是合法 JS 标识符，直接崩。真正原因八成是你想读的文件内容被复制粘贴到 JS 源码里了。你的 .js 文件现在长这样： const fs = require('fs') rd = fs.readFileSync("1.txt") console.log(rd.length)题目 AI辅助的全方位科研管理与创作平台 // ← 这一行是裸文本裸文本既不是字符串（没引号）也不是注释（没 // 或 /* */），Node 只能当代码解析，然后崩在第一个中文字符上。正确姿势 JS 文件里只留代码，文本内容留在 1.txt 里： // index.js const fs = require("fs");const text = fs.readFileSync("1.txt", "utf8"); console.log(text.length);# 1.txt 题目 AI辅助的全方位科研管理与创作平台顺手补：readFileSync 不传 encoding 的坑 fs.readFileSync("1.txt") 返回的是 Buffer，不是字符串： const rd = fs.readFileSync("1.txt"); console.log(rd.length); // 字节数，中文会算错想拿字符长度就要传编码： const text = fs.readFileSync("1.txt", "utf8"); console.log(text.length); // 字符数 console.log(Buffer.byteLength(text, "utf8"));// 字节数一个中文字符在 UTF-8 里是 3 字节，字符长度和字节长度会差好几倍——涉及"长度"就要先想清楚要哪种。触类旁通：类似的 SyntaxError 同样是"文件混了不该混的东西"，报错方向不同：报错通常原因Unexpected identifier '目' 中文文本被贴进 .jsUnexpected token '<' HTML 页面被当 JS 加载（一般是路径错）Unexpected token 'export' ESM 语法进了 CJS 文件（改 .mjs 或加 "type": "module"）Unexpected token '?' / ?? / &&= 老 Node 不认新语法，升级 NodeInvalid or unexpected token 指向文件带了 UTF-8 BOM，重存为无 BOM一句话总结看到 Unexpected identifier '中文'——先打开源码文件，把混进去的文本挪出去。readFileSync 记得传 "utf8"。