1. 装好Node.js之后大多数人卡在了同一个报错上先聊一个几乎所有Windows用户都会遇到的场景你从官网下载了Node.js安装包一路“Next”点到底安装完成界面干干净净。然后你满怀期待地打开终端敲下node -v版本号秒出一切正常。紧接着敲下npm -v屏幕上哗啦弹出一段红字npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。 有关详细信息请参阅 about_Execution_Policies。 所在位置 行:1 字符: 1很多人第一次看到这个报错直接懵了为什么node -v能用npm -v就被禁止我明明全都装好了这算哪门子“笔记”该有的体验先别急着内疚这个真不是你装错了而是Windows的PowerShell默认安全策略跟npm的启动方式产生了冲突。这个报错的高频程度基本可以排进Node.js新手问题榜前三。我见过不少开发者卡在这里一两个小时最后从网上随便复制一条“删掉npm.ps1文件”的命令解决问题结果留下一个更隐蔽的坑——以后某些工具链在PowerShell下会莫名其妙失效。这篇笔记我就围绕“装好Node.js之后接下来该做什么”这一个主线展开。会把安装、环境配置、npm报错、日常使用这几个高频环节里值得记录的细节都梳理一遍重点是让你弄明白每一步背后的原理而不只是复制命令。无论你是刚准备入门前端的初学者还是工作几年但一直在macOS/Linux上开发、偶尔需要在Windows机器上跑一套Node环境的老手这篇文章的排查思路和配置方案都值得过一遍。2. node和npm一对看似简单但总被误解的“搭档”2.1 node是什么npm又是什么先简单扫一遍基础概念。Node.js 是一个基于 V8 引擎的 JavaScript 运行时环境它让 JavaScript 可以在浏览器之外跑起来。这里的关键词是“运行时”说白了就是一个程序它的作用是解释并执行你写的 JavaScript 代码。npm 是 Node Package ManagerNode.js 官方的包管理工具。它负责三件事下载别人写好的代码包叫“依赖”或“包”、管理这些包的版本、执行包里面提供的命令脚本。Node.js 和 npm 是两个独立的东西但你几乎总是成套使用。npm 需要 Node.js 作为它的运行基础所以安装 Node.js 时通常会顺带装上 npm。这也是为什么报错信息里出现的是npm.ps1这个名字——npm 本身的入口就是一个通过 PowerShell 执行的脚本文件它不是编译好的.exe程序而是靠 Node.js 去解释执行的.ps1脚本。2.2 同一个命令两条完全不同的执行路径这里就涉及问题的核心了。当你在终端输入node -v系统找到的是C:\Program Files\nodejs\node.exe一个标准的可执行文件。Windows 看到.exe文件直接放行。当你在终端输入npm -v事情就变得复杂了。npm 在安装目录里其实有三个入口文件npmshell 脚本版本给 Linux/macOS 用的npm.cmd批处理版本给 Windows 的 CMD 用的npm.ps1PowerShell 脚本版本给 PowerShell 环境用的如果你用的是 PowerShellWindows 11 默认终端、VS Code 内置终端默认环境都是 PowerShell系统会优先寻找.ps1版本的 npm 脚本。在默认策略下Windows 禁止执行任何未经签名的.ps1脚本文件于是报错就出现了。这不是 npm 的 bug也不是 Node.js 没装好是 PowerShell 的“执行策略”在起作用。2.3 为什么有人没遇到这个报错你可能会问一个问题为什么网上有些人从来没见过这个报错好像他们装完就直接能用这里面的差异主要有三个一是安装来源不同。有些非官方渠道的 Node.js 分发包或“一键环境”脚本会在安装过程中顺手修改系统的 PowerShell 执行策略把默认的 Restricted 改成 RemoteSigned所以装完就直接可以跑。二是Windows开发者模式的差别。如果系统里开启了“开发者模式”部分安全策略会被放宽某些环境下的脚本执行限制也会被绕开。三是终端环境不同。如果你用的是 CMD命令提示符而不是 PowerShellnpm 会走npm.cmd路径完全不会触发.ps1的限制。明白这个原理之后你就能很从容地决定要怎么处理这个报错了。不要一上来就复制网上的“删文件大法”我先介绍正常的排查和修复路径这个更稳妥。3. 从安装到跑通一条最稳的路线3.1 选版本LTS 优先还是 Current 尝鲜在开始配置之前先花几十秒把“装哪个版本”这个问题解决掉。Node.js 官网提供两个版本系列LTSLong Term Support长期支持版和 Current当前版本。LTS 版本的特点是稳定、维护周期长、生态兼容性好生产环境推荐用Current 版本会更快引入新特性但迭代频繁某些依赖可能还没跟上。我的建议非常简单除非你有明确理由需要新特性否则一律装 LTS。这不是陈词滥调而是现实的教训。我见过不止一次开发机装了个奇数版本的 Node.js某个原生模块编译失败查了半天发现是 Node 版本太新依赖的编译环境还不兼容。选 LTS 能帮你规避一大批这类问题。3.2 多版本管理装上 nvm-windows 一劳永逸比直接装官方安装包更推荐的做法是先装一个版本管理工具。Windows 上最常用的是nvm-windows不是 macOS/Linux 上那个nvm但概念一致。它的核心作用就一个让你可以在同一台机器上安装多个 Node.js 版本随时切换。nvm install 20.17.0 # 安装指定版本 nvm install 18.20.4 # 再装一个旧版 nvm use 20.17.0 # 切换当前使用的版本 nvm ls # 查看本机已安装的所有版本为什么这个对你的“nodejs 笔记”来说值得单独记一笔因为实际开发里“换 Node 版本”是一个高频操作。老项目跑不起来新项目要求高版本没有版本管理工具你就得反复卸载安装非常浪费时间。3.3 安装过程中的几个勾选项如果你直接用官方安装包安装注意安装向导中间有一页是可选项默认勾选了“Add to PATH”和“npm package manager”等选项。关键的是“Add to PATH”这一项它会把 Node.js 的安装目录写进系统的 PATH 环境变量。PATH 这个东西你可以把它理解成一个“命令搜索目录清单”。你在终端里敲node系统会按照 PATH 里列出的目录一个个找看有没有叫node的可执行文件。如果没有勾选这个选项你安装完 Node.js在终端里敲node -v依然会报“不是内部或外部命令”。虽然很多安装向导默认勾好了还是值得确认一下。装完可以打开系统设置里的“编辑环境变量”看看 PATH 里有没有类似C:\Program Files\nodejs\这一条。3.4 安装完成的验证方式安装完成后打开一个新的终端窗口依次执行node -v npm -v都输出了版本号说明基础环境已经通了。注意这里强调“新的终端窗口”——如果你的编辑器或终端是在安装之前打开的PATH 环境变量的变化不会自动加载进去需要重启终端才生效。这也是一个特别容易让人误判“我是不是没装好”的细节。4. npm.ps1 被禁止运行根因、排查链路和修复方案4.1 先定位问题再动手修回到开头的报错。很多新手犯的错误是看到红字就慌了然后去网上搜一段“终极解决方案”直接复制执行完也不知道发生了什么下次换个环境又踩同样的坑。正确的做法是先做两个检查第一步确认当前使用的是不是 PowerShell。如果只是偶尔用一次最简单的绕开方式是切换到 CMD 终端# 在 CMD 中 npm -v因为 CMD 里会走npm.cmd不会触发.ps1策略限制。但这不是长久之计因为 PowerShell 已经是事实上的 Windows 默认终端VS Code 的内置终端也默认用它。第二步查看当前系统的执行策略具体是什么状态Get-ExecutionPolicy -List这个命令会列出 PowerShell 在四个作用域下的策略设置MachinePolicy、UserPolicy、Process、CurrentUser、LocalMachine。优先级从高到低排列生效的是“优先级较高的非未定义值”。如果输出的结果里有任何一项是Restrictednpm.ps1 的报错就说得通了。4.2 PowerShell 执行策略到底在管什么PowerShell 的执行策略是安全机制它决定了一个.ps1脚本能不能在当前环境里运行。常见的有四个值策略含义Restricted禁止运行任何脚本只允许交互式命令RemoteSigned本地创建的脚本可以运行从网络下载的脚本必须有数字签名AllSigned所有脚本都必须有数字签名Unrestricted所有脚本都可以运行但来自网络的脚本会先提示确认Windows 系统默认的是Restricted这就是为什么 npm.ps1 跑不了。npm 安装的脚本是本地文件但 PowerShell 无法确认它是不是安全来源索性一律禁止。注意RemoteSigned这个策略的意义它把“本地用户自己写的脚本”和“从网上下载的脚本”区分开来。npm 装包时在本地生成的脚本文件以及 npm 自带的入口脚本在RemoteSigned下都可以正常执行。4.3 三种修复方案按推荐程度排序方案一调整当前用户的执行策略推荐Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行完会提示确认输入Y回车即可。然后再运行npm -v你会发现一切正常了。为什么推荐这个方案而不是直接改成Unrestricted因为RemoteSigned仍然保留了对“网络下载脚本”的签名检查安全性和可用性之间比较平衡。而且它只修改了当前用户的设置不会影响系统级策略。方案二临时避开 PowerShell直接用 cmd 版本如果你不想动系统的任何策略做一个临时操作npm.cmd -v手动指定文件名让 npm 走.cmd路径。好处是零修改坏处是每次都要多敲一个.cmd后缀比较麻烦适合应急验证环境是否正常。方案三放开到 Unrestricted不推荐Set-ExecutionPolicy -Scope CurrentUser Unrestricted这个方案能解决问题但把安全边界放得太宽以后任何.ps1脚本都会无条件放行。个人开发机勉强可用但不值得为了一个 npm 报错放弃整条安全策略。4.4 为什么我不建议“删除 npm.ps1”网上很多“教程”会告诉你既然npm.cmd能用那把npm.ps1删掉PowerShell 找不到.ps1版本自然就会去调用.cmd版本。听起来很巧妙但这是典型的馊主意。原因有三点一是npm.ps1不光服务于 npm 本身很多 npm 全局安装的工具比如 yarn、pnpm、各种 CLI 工具在 PowerShell 下执行时也可能依赖这种.ps1入口机制。删掉之后你今天解决了npm -v的问题明天大概率会遇到一个新工具的类似报错。二是以后你想用 PowerShell 脚本做自动化比如写 CI 构建脚本、部署脚本会发现这套环境已经被你改坏了排查起来更痛苦。三是根本没必要。执行策略是 PowerShell 提供的标准机制安全地调整策略本来就是它的官方用途。与其野蛮删文件不如学会正确配置。我日常用的组合就是RemoteSigned 正常安装的 npm 入口文件不管是开新项目还是维护老项目从来没因为这个出过问题。5. 环境配置的进阶细节看完这节才算真正配好 Node.js 环境5.1 全局安装路径别把东西全堆积在 C 盘npm 允许你全局安装命令行工具比如npm install -g typescript npm install -g nodemon这些工具默认会被安装到 Node.js 的安装目录下例如C:\Program Files\nodejs\node_modules。这个默认配置有两个问题一个是 Program Files 目录权限较敏感有些操作可能需要管理员权限才能写入。另一个是如果你长期使用这个目录里的东西会越来越多挤占系统盘空间。所以实操里我一般建议把全局安装路径改到独立的地方。比如 D 盘建一个nodejs_global目录npm config set prefix D:\nodejs_global npm config set cache D:\nodejs_cache设置完成后再执行一次全局安装工具会被放到你指定的目录下。需要配合的是将这个目录也加入 PATH 环境变量否则全局命令在终端里依然找不到。5.2 registry 是什么为什么你的 npm 下载慢npm 从远程仓库下载依赖包默认的下载源是https://registry.npmjs.org/。这个源服务器在国外国内网络环境下下载速度可能会比较慢并且偶尔还会超时、中断。更高效的做法是配置国内的镜像源。比较常用的有https://registry.npmmirror.com这是原来的淘宝镜像源迁移域名后的正式地址以及腾讯云、华为云等厂商提供的 npm 镜像。配置方式非常简单npm config set registry https://registry.npmmirror.com npm config get registry # 验证配置是否生效你可以把 registry 理解为“快递发货地”。默认发货地在国外路程遥远不稳定配好镜像后发货地变成国内速度立刻不一样。需要提醒一句镜像源更新有一定的同步延迟正常情况下这个延迟几乎感知不到但如果某天你安装一个包时报“找不到版本”且确定网络没问题可以临时切回官方源确认一下是不是镜像同步的问题npm config set registry https://registry.npmjs.org/5.3 和 .npmrc 有关的配置优先级很多初学者不知道 npm 的配置是有多级优先级的。从小到大依次是项目级.npmrc项目根目录下用户级.npmrc默认在用户主目录下比如C:\Users\你的用户名\.npmrc全局级.npmrc在 npm 安装目录里npm 内置默认配置也就是说如果项目里有一个写死了 registry 的.npmrc文件你在命令行里执行npm config set registry改的全局设置对这个项目也不会生效。这个机制也解释了为什么“我明明配好了镜像源但某个项目下载还是很慢”这类问题的根源。遇到这种情况打开项目根目录找找有没有.npmrc文件有的话看看里面写的是什么。5.4 package-lock.json千万别忽略这个文件当你在项目里运行npm install安装依赖后目录下会自动生成一个package-lock.json文件。这个文件会锁定当前项目实际使用的所有依赖包的具体版本号。这个文件非常重要尤其是做一些对版本敏感的项目时。举个例子你在 package.json 里写的依赖版本是express: ^4.18.0这个^符号表示“4.x 版本里最新的”如果不去锁定每次在两个环境里跑npm install实际安装的版本可能不一样。有了package-lock.jsonnpm 在安装时会严格按照锁文件里的版本去下载保证不同环境你的电脑、同事的电脑、服务器安装出来的依赖是一致的。所以这个文件必须提交到代码仓库永远不要把它写进.gitignore。同样道理如果在一个全新环境里 clone 了项目先执行npm ci而不是npm install。npm ci是“按 lock 文件精确安装”的专用命令安装前会先删除 node_modules 再重新安装适合 CI 环境和团队协作场景。6. 从环境到项目把 Node.js 真正用起来6.1 选一个包管理器npm、yarn 还是 pnpm环境配置好之后下一步就是怎么在日常项目里用它。首先要面对的一个问题是包管理器选哪个。npm 不需要多介绍装 Node.js 自带。它的优点是零配置缺点也有——安装速度一般依赖的磁盘占用偏大。yarn 是 Facebook 早年为了解决 npm 的一些问题而推出的经典版 yarn 在那几年确实体验更好安装速度更快命令也更简洁。不过随着 npm 持续更新两者功能已经非常接近现在新项目选择 yarn 的动机比过去少了很多。pnpm 是最近几年社区口碑上升非常快的包管理器。它的核心特点是通过硬链接和符号链接把依赖包集中存储在磁盘的一个全局位置多个项目可以共享同一份文件极大地节省磁盘空间安装速度也非常快。它还通过更严格的依赖隔离机制解决了 npm/yarn 在某些场景下存在的“幽灵依赖”问题。我的个人建议是如果你在维护老项目项目里已经选好了包管理器那就顺着项目的用法走。如果是全新项目可以优先考虑 pnpm。它的技术方案更现代实际体验也稳。6.2 创建第一个项目package.json 的诞生用一个空目录创建项目mkdir my-project cd my-project npm init -y执行完成后目录下会生成一个package.json文件它是整个 Node.js 项目的“身份证”和“配置中心”。一个典型内容类似这样{ name: my-project, version: 1.0.0, description: , main: index.js, scripts: { start: node index.js, dev: nodemon index.js }, dependencies: { express: ^4.18.2 }, devDependencies: { nodemon: ^3.0.1 } }有两个字段值得花点篇幅说明。dependencies是生产环境运行时的依赖。比如 Web 服务框架 express、数据库驱动等项目部署上线时依然需要它们。devDependencies是开发阶段才需要的依赖。比如构建工具、类型检查工具、代码格式化工具它们只在开发时起作用项目在服务器上跑起来之后就不需要了。安装依赖的命令对应关系是npm install express # 默认写入 dependencies npm install -D nodemon # 写入 devDependencies6.3 为什么 npm run 能调用 node_modules 里的命令安装依赖后你大概率会接触到npm run dev、npm run build这类命令。它们是在执行package.json里 scripts 字段定义的内容。很多人疑惑的一个点是全部依赖都装在node_modules目录下为什么执行npm run dev时系统能找到nodemon这个命令它不是应该出现“不是内部命令”的报错吗这里有一个细节npm 在执行脚本时会把node_modules/.bin目录临时加入 PATH 环境变量。也就是说你安装的所有带“可执行命令”的依赖包它们的可执行文件都链接在node_modules/.bin里npm run 的时候就会自动把它们暴露出来。这也是为什么某些全局工具在终端里敲不出来因为没配 PATH但在npm run脚本里反而能正常执行的原理。7. 实际使用中值得记一笔的几个“小坑”7.1 安装路径带空格带来的麻烦Windows 默认安装路径是C:\Program Files\nodejs注意 “Program Files” 中间有空格。多数情况下Node.js 自身处理得很好不会出问题。但当你用 npm 全局安装一些依赖原生模块比如 node-sass、有些数据库驱动这类模块在编译时会去调用安装路径下的文件路径里的空格可能导致编译脚本解析出错。如果遇到这类问题解决方案是把 Node.js 安装到一个无空格的路径下比如C:\nodejs或D:\Software\nodejs。这不是必须做的预防性操作只是遇到相关报错时的一个排查方向。7.2 全局命令找不到先别急着重装修改完 PATH 或全局安装了一个新工具后如果你在终端里执行这个命令提示找不到首先确认你当前打开的终端是不是在环境变量修改之前就启动的。如果是重新开一个终端窗口再试。这个“重启终端”的操作虽然简单但能解决一大半的“我装了怎么不能用”问题。和前面安装完 Node.js 的情况一模一样PATH 是进程启动时读取的已启动的终端不会自动感知新的环境变量。7.3 切换 Node 版本后 node_modules 可能罢工如果你用了 nvm-windows 这类工具切换 Node.js 版本有时候会碰到一个情况切到另一个版本后项目里npm run dev启动失败报一堆模块错误。原因很简单node_modules 里的某些依赖尤其是带原生编译代码的模块是针对旧的 Node 版本编译的版本一变二进制不兼容就得重新编译。解决办法是删掉 node_modules 重新安装rm -rf node_modules npm install在 Windows 上如果你不想用命令行也可以直接在文件管理器里删除。只是注意重新安装依赖可能比较耗时。另外有个偷懒技巧切换版本后先别急着删运行npm rebuild试试这个命令专门用来重新编译当前项目下的原生模块成功率挺高而且快得多。7.4 npm 缓存占用和“安装卡住”的处理npm 下载依赖时会使用本地缓存默认放在系统盘的 npm cache 目录。装的项目多了之后这个缓存可能会占用几个 GB 甚至更多。查看缓存大小和清理的方式npm cache ls # 列出缓存 npm cache clean --force # 强制清理如果你遇到“某次 npm install 卡住”的情况大概率是网络问题或镜像源不稳定造成的。排查思路先看 registry 配置确认是官方源还是镜像源再看是偶发的单包下载超时还是整个依赖树都装不下来。前者可以重试后者可以检查网络环境和镜像配置。千万不用一上来就清理缓存缓存一般不是安装失败的根因。8. 个人经验配置 Node.js 环境远比想象中简单最后分享一点个人体会。“nodejs 笔记”这个项目标题听起来很宽泛但我越来越觉得学 Node.js 的第一道坎其实是环境配置。很多人不是被 JavaScript 的异步、回调、事件循环这些概念劝退的而是倒在了npm.ps1报错和 PATH 配置上。这些问题的根源往往不是技术复杂而是没有人把背后的机制讲清楚。我的建议是配环境这件事一定要“知其所以然”。今天这个报错如果你只是复制了一条命令明天换个环境还会踩但如果你理解了 PowerShell 执行策略、PATH 原理、registry 作用这几件事以后不管在什么设备上配环境都能独立排掉九成以上的问题。文末再补一个小技巧装完 Node.js 后顺手在终端里执行一条npm config list把当前的所有配置过一遍。这个命令会同时显示出 registry、prefix、cache 等关键配置项花十秒钟看一眼比到时候遇到问题再反复猜要高效得多。