如果你在Windows上刚刚接触Node.js大概率会遇到这样一个场景装好Node之后打开PowerShell想跑个npm -v看看版本结果屏幕直接给你一行红色错误npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。 我当年第一次装Node.js被这行字卡了一下午重装了三遍都没用甚至一度以为是安装包有毒。后来才明白真正的问题出在Windows PowerShell的执行策略上和Node.js本身一点关系都没有。这篇笔记就是把我从零开始装配Node.js环境的整个过程记录成文。内容包括版本怎么选、安装包怎么挑、全局目录怎么规划、npm执行脚本报错怎么解决、第一个项目怎么跑起来、多版本怎么管理。只要你准备在Windows上学习或使用Node.js这篇内容应该能帮你少走不少弯路。我会尽量少说概念术语多用实际操作说话。1. 初装Node.js前先理清这几个基础概念1.1 Node.js到底是什么为什么前后端都用它很多人第一次接触Node.js是从前端要学Node这句话开始的。它本质上是一个运行环境让JavaScript可以脱离浏览器在电脑上直接执行。以前JavaScript只能在浏览器里操作网页有了Node.js之后你就能用它读写文件、启动服务、操作数据库甚至写命令行工具。所以无论你现在是想学前端工程化还是想用JS写后端接口Node.js都是绕不开的一环。我遇到不少初学者喜欢先啃概念动手装环境反而随便结果一上来就被报错劝退。这里我的建议是先把Node.js是JS的运行时、npm是它的包下载器这两点记住就够了剩下的都是在实际使用中慢慢理解的。不用先去研究事件循环、非阻塞I/O那些底层机制那都是后话。等你的项目跑起来遇到性能问题再回头看比一开始钻牛角尖有效得多。1.2 npm和Node.js的关系以及那个特别的npm.ps1npm全称是Node Package Manager它会随着Node.js安装包一起装好。它的作用是帮你下载和管理别人写好的JavaScript模块你把依赖写在package.json里npm负责把对应的包拉下来放进node_modules文件夹。类比一下Node.js是操作系统npm就是应用商店。没有npm你就得手动去一个个下载源码、手动处理依赖关系那基本等于回到原始时代。问题来了在Windows上安装完Node.js后你会在安装目录里看到好几个跟npm有关的文件最简单的有npm、npm.cmd、npm.ps1。这三个名字看起来差不多但各有用途npm是Shell脚本主要给Unix类系统用npm.cmd是给CMD调用的批处理npm.ps1是给Windows PowerShell用的脚本。PowerShell为了安全默认会限制.ps1脚本的执行一旦你的系统策略是禁止运行脚本那么当你敲npm时PowerShell尝试加载npm.ps1就被拒绝了。所以你会看到那种很吓人的红字报错但CMD里却一切正常。理解这个原理后面排查问题就有方向了。2. 安装与验证从下载到node -v的全部细节2.1 LTS还是Current不同场景下的选择策略打开Node.js官网首页会给你两个下载按钮一个标着LTS一个标着Current。LTS是Long Term Support的意思这类版本会得到长期维护API稳定大部分生产环境都会用LTS。Current则是最新功能版本能提前用上新特性但可能不够稳定升级大版本时也可能出现兼容性问题。我给新手的建议很直接默认选LTS。尤其是你要用来练习、学习、做毕业设计或者公司项目LTS是最稳妥的。只有在你明确需要某个新语法或新API并且愿意承担小概率踩坑的时候才去碰Current。我自己就干过傻事装了最新Current版本跑老项目结果某个依赖怎么都装不上最后查了半天是Node版本太新。从那以后我本机默认装LTS需要测新特性再切版本。2.2 下载渠道和安装包类型我推荐哪一类Node.js的下载渠道有官方站和国内镜像。官方站下载地址是nodejs.org如果你的网络下载速度一般也可以用npmmirror提供的二进制镜像也就是很多人熟知的淘宝镜像里面会同步Node.js的各个发行版本。但要注意镜像站只提供文件文档和更新日志还是以官方为准。安装包形式通常有两种.msi和.zip。.msi是Windows安装程序双击之后一路Next会自动帮你把Node.js和npm装好还会写入系统环境变量PATH适合绝大多数人。.zip是绿色解压版解压后需要手动把node.exe所在目录加进PATH适合想完全掌控文件结构的高级用户。如果你是第一次装直接选.msi不用犹豫。2.3 安装完成后先别急着跑npm按这个顺序验证安装过程没什么特殊的基本就是同意协议、选择安装路径、点下一步。有一点需要提醒安装路径尽量不要选带中文的目录虽然很多情况下中文路径也能跑但后续一旦出问题排查起来会非常痛苦。默认的C:\Program Files\nodejs虽然有空格但这是Node官方支持过的路径npm自己也在这个目录下一般没问题。装完后先打开CMD不是PowerShell是CMD。输入node -v如果输出类似v20.18.1的版本号说明Node.js本体装好了。接着输入npm -v如果也输出版本号说明npm正常。为什么要先用CMD验证因为CMD不会加载.ps1脚本即使你PowerShell执行策略有问题CMD里的npm大概率也是正常的。这样能帮你快速把问题范围缩小如果CMD里两个命令都正常那Node.js环境就没坏出错的地方多半是PowerShell配置。3. 把全局包和缓存目录迁出C盘环境变量一次配好3.1 为什么要迁移全局包塞满C盘的惨痛教训默认情况下npm的全局包会安装到Node.js安装目录下的node_modules里或者用户目录下的AppData文件夹里。一开始你可能没感觉等到你开始大量安装全局工具包比如http-server、nodemon、vue-cli、create-react-appC盘空间会一点一点被吃掉。更麻烦的是有些工具在系统盘目录下需要管理员权限才能写入运行命令时经常会有各种权限问题。我自己的电脑C盘是SSD容量本来就不大有段时间频繁装全局工具装了一圈下来发现C盘少了几个G。后来一气之下把所有npm全局包和缓存都迁到了D盘从此清净了。建议大家从一开始就规划好目录别等到C盘爆红再折腾。迁移这件事本身不难难的是下定决心因为改完之后旧工具可能需要重装。3.2 新建目录并读取当前配置先确定两个目录一个是全局包存放目录一个是npm缓存目录。比如我想把这两个目录放在D:\Nodejs\global和D:\Nodejs\cache就先在D盘把这两个文件夹建好。建完之后可以在命令行里用两条命令确认当前npm的配置指向哪里npm config get prefix npm config get cache通常你会看到npm默认的prefix是Node.js安装目录cache是用户目录下的npm缓存目录。接下来就要把这两个路径改掉。改之前记住旧路径也有用因为万一你想回退还能找到原来的位置。3.3 修改npm全局前缀和缓存位置并配置系统变量执行下面两条命令把prefix和cache指到新建的目录npm config set prefix D:\Nodejs\global npm config set cache D:\Nodejs\cache执行完可以用npm config get prefix和npm config get cache确认是否生效。但这只是改了npm内部的配置系统还不认识D:\Nodejs\global里的命令。接下来打开系统属性里的环境变量设置在用户变量或系统变量的Path中新增一行D:\Nodejs\global。同时再新建一个环境变量名为NODE_PATH值设为D:\Nodejs\global\node_modules。NODE_PATH的作用是让Node.js在解析模块时能感知到全局包的位置。以后如果你用npm install -g装了某些全局工具它们生成的可执行文件会放进D:\Nodejs\global依赖模块则待在D:\Nodejs\global\node_modules里。配置完之后需要重新打开一个终端窗口环境变量才会刷新。然后可以随便全局装个小工具测一下比如npm install -g http-server再执行http-server --version只要能输出版本号说明系统已经能识别新路径了。4. 遇到npm.ps1权限报错完整排查与三种解法4.1 报错复现什么情况下最容易触发在新装的Windows系统里PowerShell默认的执行策略是Restricted也就是禁止运行所有.ps1脚本。所以只要你在PowerShell里敲npm、npm install、npm run dev这类命令一旦内部要走npm.ps1就会被策略拦下来显示类似这样的一段话npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。 有关详细信息请参阅 https:/go.microsoft.com/fwlink/?LinkID135170 中的 about_Execution_Policies。 CategoryInfo : SecurityError FullyQualifiedErrorId : UnauthorizedAccess很多人看到SecurityError就以为是杀毒软件或者权限问题其实不是。它仅仅是PowerShell认为运行这个脚本不合规和Node.js本身没有任何关系。4.2 排查链路先分清是npm问题还是PowerShell问题遇到这个报错我们可以按这样一个顺序排查先跑node -v如果正常说明Node.js的核心文件没问题。再跑npm.cmd -v注意是带.cmd后缀的npm。如果这个能输出版本号说明npm也没有问题只是PowerShell不走.cmd只认.ps1。在PowerShell里运行Get-ExecutionPolicy如果返回Restricted就基本可以确定是执行策略的锅。运行Get-ExecutionPolicy -List可以查看当前用户、本地机器等不同作用域下的策略有时候某个策略里已经对外开放了但另一个作用域还在限制。这样排查完你就能很清楚地知道问题不是出在Node.js而是出在PowerShell的安全策略。知道根因之后选一种解法就行。常见的情况可以简单对个表症状可能原因下一步操作node -v 正常npm -v 报错PowerShell执行策略限制检查Get-ExecutionPolicyCMD里npm正常PowerShell报错只影响PowerShell修改CurrentUser执行策略CMD里npm也不认识环境变量PATH没配好检查Node.js安装目录是否在PATHnpm install超时或连接拒绝网络到官方源不稳定切换镜像源4.3 解法一调整当前用户的执行策略最推荐最常用的做法是只调整当前用户的执行策略不改系统级别的配置。操作也很简单在PowerShell窗口里运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser系统会询问是否要更改执行策略输入Y回车确认。之后再运行npm -v就能正常输出了。这里解释一下RemoteSigned的含义它允许运行本地创建的脚本也可以运行从网络下载的脚本但网络下载的脚本必须带有可信数字签名。npm.ps1是Node.js安装时写在你本地的文件所以属于本地脚本可以被正常执行。相比UnrestrictedRemoteSigned已经安全很多。这也是微软官方比较推荐的一个策略组合。有一点要注意如果你用的Scope是LocalMachine那通常需要管理员权限但CurrentUser作用域只需要当前用户权限即可不用专门右键以管理员身份运行。4.4 解法二直接用CMD或Git Bash绕过PowerShell如果你并不想修改PowerShell的任何策略另一个简单粗暴的办法就是以后不要用PowerShell跑npm直接用CMD、Git Bash或Windows Terminal里新建的CMD窗口。CMD执行的是npm.cmd根本不经过PowerShell的脚本策略检查所以不会报这个错。很多前端工具链命令在CMD里都能正常运行比如npm install、npm run build。但如果你在项目里配了某些需要PowerShell特性的脚本比如自定义的ps1脚本那还是得彻底解决执行策略问题。我的个人习惯是日常命令行工具窗口用Windows Terminal默认启动PowerShell所以最终还是把策略调成了RemoteSigned一劳永逸。4.5 解法三修改npm的脚本shell或者直接调用npm.cmd还有一类情况是PowerShell执行策略本身没问题但你看到某个脚本文件带.ps1后缀被阻止可能是在运行npm run xxx时npm内部用了PowerShell去执行package.json里的脚本。这时可以在npm配置里指定shellnpm config set script-shell C:\\Program Files\\git\\bin\\bash.exe这样npm在执行脚本时会走Git Bash而不是PowerShell。前提是你本机装了Git Bash。临时应急时也可以在PowerShell里直接敲npm.cmd -v或者在Node安装目录下找到npm.cmd用完整路径调用。不过这些方案都绕不开一个事实你的PowerShell策略始终在限制脚本执行。所以我的建议还是优先改执行策略这不是什么危险操作只要选对作用域和策略级别安全性是可控的。5. 跑通第一个项目npm init到依赖安装的完整链路5.1 用npm init生成package.json字段含义与默认值环境配好之后我们来跑一个最小的项目。先在某个工作目录下新建一个文件夹然后进入这个文件夹运行npm init -y-y表示跳过交互式提问直接生成一份默认的package.json。打开它你会看到类似这样的内容{ name: my-project, version: 1.0.0, description: , main: index.js, scripts: { test: echo \Error: no test specified\ exit 1 }, keywords: [], author: , license: ISC }这些字段里name是项目名version是版本号main是入口文件scripts可以定义常用命令。很多初学者不关心package.json是怎么来的直接复制别人的配置这样也可以但自己动手过一遍理解每个字段干嘛用的后面遇到问题时能少走很多弯路。5.2 安装依赖的完整链路dependencies与devDependencies在项目里安装一个运行时依赖最经典的例子是Expressnpm install express执行完你会发现文件夹里多了一个node_modules目录package.json里也多了一条依赖。node_modules里放着Express以及它的所有依赖包这就是npm帮你下载好的代码。如果你装的是只在开发阶段用到的工具比如代码热重载工具nodemon推荐安装到devDependenciesnpm install -D nodemondependencies里的包是生产环境运行时要用的devDependencies里的包只在开发构建时需要。区分它们很重要比如部署到服务器时通过npm install --production可以只装生产依赖避免把一堆开发工具也拖到线上。5.3 锁定版本与package-lock.json的意义装完依赖后项目里还会多一个package-lock.json文件。它记录了每个实际安装的依赖的精确版本号包括依赖的依赖。这个文件建议提交到Git仓库里这样别人拉下代码后执行npm install可以装出跟你本地完全一样的版本避免出现我这边跑得好好的你那边就是起不来的版本不一致问题。如果以后想把依赖清理重装到锁定版本可以用npm cinpm ci会严格按照package-lock.json里的版本安装并且会先删除node_modules再重新安装速度通常比npm install更稳定。我第一次遇到npm ci是接手一个老项目时同事告诉我的当时npm install总报依赖冲突换成npm ci后一口气就好了所以印象很深。5.4 换镜像源提速以及常见报错国内下载npm包经常很慢官方源是https://registry.npmjs.org/网络不好时会出现各种超时错误。办法是把registry切换到国内镜像我目前比较常用的是npmmirror的源npm config set registry https://registry.npmmirror.com设置完之后可以用npm config get registry确认。这样一来npm install的下载速度会有明显提升。如果你只想在某个命令里临时换源不用全局改可以直接在install时加参数npm install express --registryhttps://registry.npmmirror.com常见的安装报错我遇到过这几种ECONNREFUSED一般是网络或代理问题ETIMEDOUT是超时ERESOLVE通常是依赖版本冲突可以试试npm install --legacy-peer-deps或者用npm update后再装。如果怀疑是缓存坏了可以执行npm cache clean --force再重新安装。这些都是老生常谈但在紧急情况下真的能救命。6. 安装进阶nvm多版本切换与镜像源提速6.1 为什么用nvm-windows而不是Linux/Mac上的nvm很多教程提到用nvm管理Node版本但Linux和macOS上的nvm是一个Shell脚本而Windows上的nvm-windows是另一套独立的工具两者并不是同一个实现。如果你在Windows上去搜nvm install的教程一定要确认对方用的是不是nvm-windows否则可能看了半天还是装不上。nvm-windows的安装包可以到它的GitHub仓库下载装完之后先用管理员权限打开CMD或PowerShell然后就可以执行nvm install 20.18.1 nvm install 22.11.0 nvm use 20.18.1nvm ls能列出当前已装的版本nvm current能查看当前正在用的版本。日常开发中有时候老项目需要低版本Node有时候新项目要求高版本靠nvm-windows来回切换是非常高效的。6.2 安装nvm-windows前必须先卸载已有Node.js这一点特别关键。如果你已经用安装包装过Node.js在装nvm-windows之前最好先把原来的Node.js卸载干净包括删掉系统环境变量里的Node路径否则nvm通过符号链接切换版本时会跟旧安装冲突。我自己就踩过一次当时舍不得卸载旧版Node装完nvm后一执行nvm use跑node -v还是旧版本排查了很久才意识到是旧安装残留的PATH排在前面把nvm的链接路径盖住了。卸载干净之后再安装nvm-windows然后安装你需要的Node版本。注意nvm-windows本身安装的目录最好也不要有中文否则后续装版本时可能出现权限或路径识别问题。6.3 日常切换版本与全局包处理切换版本后有一个容易被忽略的问题全局包不会自动跟着新版本走。比如你在Node 20里全局安装了nodemon切到Node 22后再想运行nodemon可能就提示不是内部或外部命令了。这是因为每个Node版本安装后全局包目录是独立的。解决方案有两个一是切换版本后手动重新安装所需的全局包二是尽量少用全局包把项目依赖放在项目内的node_modules里用npx来调用临时工具。npx是npm自带的命令它会在当前项目里找命令找不到时会临时下载并执行用完即走特别适合不想污染全局环境的人。6.4 镜像源配置的完整命令与注意事项nvm-windows本身下载Node.js发行版时走的也是官方源国内经常很慢。可以通过设置环境变量来加速NVM_NPMJS_MIRRORhttps://registry.npmmirror.com NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node/设置前者的作用范围是npm包镜像设置后者的作用范围是Node.js二进制发行版镜像。具体变量名视nvm-windows版本略有差异建议安装后先看下它的README。设置完环境变量需要重新打开终端再执行nvm install不然有可能不生效。这里要特别提醒不要把npm源和nvm的Node二进制源混为一谈。npm config set registry只能加速npm安装JavaScript依赖包的速度而nvm下载的是Node.js本身的压缩包换的是另一个镜像地址。两个都配置好整个流程才会顺畅。说到最后我还想补充一个个人经验每次配置完环境变量或者nvm切换版本后别急着开干先执行node -v、npm -v确认当前环境再跑项目。这个习惯帮我省了很多为什么明明装了还提示找不到的排查时间。Node.js环境这件事看着简单但每个小细节都可能成为坑点。把基础打扎实后面不管是学框架还是写脚本都会顺畅很多。