PowerShell禁止运行脚本？四步解决npm run dev报错

在 Windows 上做前端开发，几乎每个人都有一道躲不开的坎：代码写完了，忐忐忑忑打开终端，输入npm run dev，结果回车之后没有等来 Vite 或者 Webpack 的启动页，反而等来一串红字——npm : 无法加载文件 D:\app\nodejs\npm.ps1，因为在此系统上禁止运行脚本。新手往往第一反应是“是不是我 Node.js 装坏了”“是不是这个项目有毒”，然后就开始卸载重装、换目录、重新配置环境变量，折腾半天还是报错。

别慌，这篇就是来给你兜底的。先说结论：你的 Node.js 大概率没有装坏，项目本身也没问题，真正拦路的是 Windows 的 PowerShell 执行策略（ExecutionPolicy）。这篇内容会从报错原理讲起，给你一套保姆级四步修复流程，再把我在实际排查中碰到的各种“改了策略还是不行”的坑也一并交代清楚。不管你是一行命令都还没敲明白的小白，还是已经看腻了报错的老手，只要照着走，基本都能让npm run dev顺利跑起来。

1. 先把报错看明白：不是 npm 坏了，是 PowerShell 在拦你

1.1 报错信息逐行拆解，先看清“禁止运行脚本”是谁干的

先看完整报错长什么样。下面这个就是我实际遇到的标准场景，路径可能每个人不一样，但结构和错误类型是相同的：

PS C:\Users\zhang\my-project> npm run dev npm : 无法加载文件 D:\app\nodejs\npm.ps1，因为在此系统上禁止运行脚本。有关详细信息，请参 阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。 所在位置 行:1 字符: 1 + npm run dev + ~~~ + CategoryInfo : SecurityError + FullyQualifiedErrorId : UnauthorizedAccess

这里有几个关键信息值得注意。第一，报错发生在D:\app\nodejs\npm.ps1，说明系统把npm命令解析到了这个.ps1文件；第二，错误类型是SecurityError，错误码是UnauthorizedAccess，翻译过来的意思很清楚：PowerShell 认为当前环境不允许运行.ps1脚本，所以直接把命令拒绝了。

很多人一看到npm.ps1里的ps1后缀就蒙了，其实.ps1就是 PowerShell 脚本文件。npm 在安装到 Windows 后，会同时生成几个不同后缀的命令文件：npm.cmd给 CMD 用，npm.ps1给 PowerShell 用，还有一个不带后缀的 shell 脚本给 Git Bash 用。你在 PowerShell 里输入npm，PowerShell 会优先执行npm.ps1这个脚本，而它恰好被安全策略挡在外面。

给小白打个比方：PowerShell 执行策略就像小区门口的保安，他在上岗前收到一条规矩——“没有通行证的外来人员一律不许进”。npm 安装时确实把脚本放到了小区里，但保安认的是脚本上有没有被允许运行的“通行证”，也就是执行策略。他一看没有放行记录，直接把人拦下了，然后回头告诉你：“不是你的脚本不行，是规则不允许它进。”

1.2 为什么 Windows 默认不让你运行 npm.ps1

Windows 的 PowerShell 里面有一套脚本运行防线，叫执行策略。这套策略有几个档位，默认情况下，Windows 客户端的策略是Restricted，也就是“全部禁止运行脚本”。你可以理解为，它允许你手工敲命令，但不允许你去执行任何.ps1脚本文件。

在系统还停留在恶意脚本泛滥、很多用户还没安全意识的时候，这条限制算是一种保护。但是放到现在的前端开发背景下，Node.js 生态的工具链，像 npm、yarn、pnpm，在 PowerShell 环境下都是靠.ps1脚本运行的，默认策略就直接把所有现代前端命令都卡死了。

有一个被问烂的问题特别有意思：“我安装 Node.js 的时候没报错啊，怎么到了 npm run dev 就报错了？”原因是 Node.js 的安装包走的是 MSI 安装器，安装时调用的命令并不受 PowerShell 执行策略限制。安装完成后，你打开 PowerShell 执行npm run dev，工具链才开始以脚本形式跑起来，这个时候策略才真正发挥作用。所以严格来说，这个报错不是安装阶段的问题，而是首次运行阶段的问题。

1.3 同一个 npm，为什么 CMD 里能用、PowerShell 里报错

这里有个非常反直觉的现象，我见过很多人在搜索引擎里搜了一圈，焦头烂额，然后忽然发现：“我切到 CMD（命令提示符）里执行 npm -v 居然能用，怎么回到 PowerShell 就报错？”

原因就是两种终端的脚本执行机制不一样。CMD 里面调用的是npm.cmd文件，它是批处理脚本，不受 PowerShell 的 ExecutionPolicy 管；而 PowerShell 里面会去执行npm.ps1，它要被 ExecutionPolicy 检查。所以你在 CMD 里能顺畅跑通npm -v，不代表在 PowerShell 里也能跑通。

了解这一点之后，你的心态会好很多：这不是环境坏了，而是“门卫”差异。只要我们把 PowerShell 这扇门也打开，问题自然就解决了。

2. 保姆级修复四步走：一条命令解除限制

2.1 修复前自检：CMD 里的 node 和 npm 是否正常

在改任何配置之前，先做一次基础检查。按下组合键Win + R，输入cmd然后回车，打开系统自带的命令提示符窗口。接着分别执行：

node -v npm -v

正常情况下，你会看到类似这样的输出：

v20.11.0 10.2.4

如果你在 CMD 里能正常显示 Node.js 版本号，就能基本确认 Node.js 本身的安装和环境变量路径没有大问题。如果这一步已经报错，比如出现“node 不是内部或外部命令”，那问题就另说了，多半是安装时没有勾选加入 PATH，或者环境变量配置有误，这时候要先去解决 PATH 的问题，而不是急着处理 PowerShell 报错。

我遇到过一部分用户，安装 Node.js 时图省事一路 Next，没有勾选 “Add to PATH”，安装完成之后，Node 命令在各个终端里都找不到。这种情况下，npm run dev的报错反而不是重点，先保证node -v能通再说。

2.2 管理员 PowerShell：把权限先拿到手

自检没问题之后，我们开一个“有权限”的 PowerShell。点击 Windows 的开始菜单，在搜索框里输入PowerShell，会在结果里看到“Windows PowerShell”或者“终端”，注意不要直接回车打开，要右键选择“以管理员身份运行”。也可以直接在键盘上按Win + X，在弹出的快速菜单里选择“终端(管理员)”或者“Windows PowerShell(管理员)”。

为什么要管理员身份？因为后面的Set-ExecutionPolicy命令默认会往整个计算机的策略层级里写，如果权限不够，系统会直接拒绝执行，白白浪费时间。而且以管理员身份打开，也可以避免后续在部分目录操作时出现“拒绝访问”的权限问题。

打开之后，窗口标题栏会显示“管理员”字样，而且命令行提示符开头会变成类似PS C:\Windows\system32>的样子。到这个状态，权限已经到位了。

2.3 核心命令：修改 PowerShell 执行策略

这一步是整个修复流程的关键。先在管理员 PowerShell 里执行下面这行命令，看一眼当前各个层级的策略到底是什么状态：

Get-ExecutionPolicy -List

你会看到类似这样的表格：

在没改过的情况下，LocalMachine那一行基本就是Restricted。也就是说，整台电脑默认禁止运行脚本。

然后执行核心命令，把它改成RemoteSigned：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

执行后系统会问你是否要更改执行策略，输入Y然后回车。接着再执行一次Get-ExecutionPolicy，看到输出变成RemoteSigned，就说明当前生效了。

这里我特别提醒一下：命令里务必带上-Scope CurrentUser。如果不带，Set-ExecutionPolicy会默认写进LocalMachine这个全局范围，需要额外确认管理员权限，而且在部分电脑上会收到“因为系统上未启用脚本执行”之类的提示，容易让新手误以为命令失败了。第一次执行可以先用我这条带-Scope CurrentUser的版本，它只对当前 Windows 用户生效，不会影响电脑上其他账号，也更安全。

关于RemoteSigned这个档位，可以简单理解为：本地创建的脚本可以直接运行，从互联网下载的未签名脚本不允许运行。Node.js 安装时生成的npm.ps1是本地脚本，所以可以被正常执行。不要为了省事去把策略设成Unrestricted，那样等于全开绿灯，会显著降低电脑对下载脚本的防护，没必要为了一次项目启动去换这个风险。

2.4 返回项目目录，跑通 npm run dev

执行策略改完之后，让我们回到项目目录。先退出当前的管理员 PowerShell，重新开一个普通 PowerShell 窗口，或者直接在原来的窗口里切换到项目路径：

cd D:\projects\my-vite-app

如果项目路径在另一块磁盘，比如路径是D:\code\demo，你需要先输入盘符加冒号切换，比如：

d: cd code\demo

然后执行：

npm -v

能看到版本号，就说明 PowerShell 已经能正常执行 npm 脚本了。接着直接跑：

npm run dev

正常情况下，Vite 项目会输出类似这样的内容：

> my-vite-app@0.0.0 dev > vite VITE v5.2.8 ready in 1200 ms ➜ Local: http://localhost:5173/

看到这个，说明你已经彻底绕开了“禁止运行脚本”的拦截，开发服务成功启动，直接在浏览器里打开本地地址就能调试了。

3. 改完还是报错？这里是我被坑过的排查清单

3.1 终端没认对：PowerShell 和 CMD 的命令提示符不一样

如果你已经按照第 2 章的步骤改了策略，回到项目目录后依然报一模一样的错误，先低下头看看你当前这个窗口的提示符长什么样。如果最左边写的是PS C:\...>，那是 PowerShell 环境，策略生效没问题；如果只是C:\...>，那就是 CMD 环境。

还有更隐蔽的情况：有的教程让你打开“终端”，Windows 11 上这个“终端”默认还是会打开 PowerShell 标签页，但你在标签页里看到的策略已经改好了，却因为同时开了多个标签页、某个标签页还停留在老的会话状态而出现误判。这种时候，最快的方式是把所有终端窗口全部关闭，重新开一个新窗口，再跑一次npm run dev。

如果实在不想重新开窗口，也有个临时绕法：在 PowerShell 里直接执行npm.cmd run dev，因为这个命令指向的是 CMD 版本的 npm 脚本，不经过 PowerShell 执行策略检查。这个方法只适合应急，不建议当成常规操作，因为它会绕过你刚建立的规则，而且以后碰到某些脚本变量时行为可能和正常 npm 命令有细微差异。

3.2 权限不够：VS Code 内置终端是最容易被忽略的坑

场景很常见：你在管理员 PowerShell 里把执行策略设置好了，测试npm -v也正常，于是兴奋地回到 Visual Studio Code，想用它的快捷键 `Ctrl + `` 打开内置终端跑项目，结果又飘红。

问题出在 VS Code 的终端权限继承机制上。VS Code 默认是以当前用户权限启动的，它内部终端里的进程权限上限，不会高于 VS Code 本身。如果你要操作的工程目录恰好放在C:\Program Files这类受系统保护的位置，或者目录是在管理员账户下创建的，普通权限的 VS Code 终端操作起来就会处处受限。

我的习惯是：开发项目老老实实放在用户目录或者 D 盘某个自己创建的目录下，不要放在系统盘的高权限目录。如果你确实需要在受保护目录下工作，那就右键 VS Code 选择“以管理员身份运行”再打开项目。除此之外，检查一下 VS Code 设置里 “Terminal > Integrated > Default Profile” 是否被设置成了 PowerShell，如果显示的还是老版本 PowerShell，也会出现策略改了但 VS Code 不识别的情况。

3.3 Node 路径混乱：有多个 node.exe 在打架

还有一种非常隐蔽的情况：你的电脑上装过不止一个 Node.js。也许是之前手动装过一个稳定版，后来又通过 nvm-windows 装了版本，或者某次安装新版本时没有卸载干净，结果环境变量 PATH 里有好几条 Node 路径。

这时候你执行npm -v看到的版本，可能不是你以为的那个版本，真正在背后生效的npm.ps1也可能在一个你完全没改过权限的目录里。排查方法很简单，在终端里执行：

where.exe node where.exe npm

系统会把所有匹配到的路径都列出来。如果列出来两三条，那就说明环境变量里有冲突。处理方案是：打开“系统属性 → 环境变量”，把 PATH 里重复的 Node.js 路径清一下，保留一个你打算长期使用的版本，然后彻底关掉终端窗口再重新打开。这一步不做彻底的话，就算策略改成Unrestricted，它也可能跑到旧的 Node 目录里去执行一个旧脚本，问题照样出现。

3.4 被组策略或安全软件锁死的情况

如果你在Set-ExecutionPolicy的时候发现命令执行完，再查看Get-ExecutionPolicy -List，某一行的策略仍然是Restricted，而且怎么改都改不动，那很可能是系统层面的组策略把这些入口接管了。这种常见于公司下发的办公电脑或者部分企业定制系统。

个人电脑的话，可以打开“运行”对话框，输入gpedit.msc进入本地组策略编辑器，依次找到“计算机配置”下的“管理模板 → Windows 组件 → Windows PowerShell”，把“打开脚本执行”这一项配置为“允许本地脚本和远程签名脚本”。但如果是公司配的电脑，我不建议你自己去折腾这些系统策略，最好直接联系 IT 管理员，拿到明确授权再处理。不要因为一个开发环境问题去绕过公司的统一安全管控，这一点要拎清楚。

另外，少部分第三方安全软件会对脚本执行进行二次拦截。如果你确定执行策略已经是RemoteSigned，但每次跑脚本还是报类似“此操作已取消”的提示，可以打开安全软件的信任区，看看npm.ps1和 Node.js 的安装目录是不是被拉黑了。

3.5 npm.ps1 被误删，需要重建文件

有一种比较容易误判的情况：npm -v报的不是策略错误，而是类似“无法将 npm 项识别为 cmdlet、函数、脚本文件”的提示，或者提示找不到路径。这说明npm.ps1文件本身已经不在了。

最常见的丢失时机，是杀毒软件把 npm 的.ps1脚本当成了潜在威胁直接隔离。你可以打开资源管理器，去 Node.js 安装目录，比如D:\app\nodejs下面，看看有没有npm.ps1、npm.cmd这些文件。如果没有，最省事的办法是去 Node.js 官网重新下载安装包，覆盖安装一遍，文件就回来了。覆盖安装不会影响你已经装好的项目依赖，这个可以放心。

4. 比改完立刻跑通更值得养成的开发习惯

4.1 不想动全局策略，就用临时 Bypass

前面推荐的是改CurrentUser范围的RemoteSigned，这是长期开发环境最常用的方案。但如果你只是在某个特定场景下跑一次命令，比如帮别人调个 bug，不想在别人电脑上留下永久设置，可以用临时放行方案：

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

-Scope Process的意思是只对当前这个 PowerShell 窗口进程生效，关掉窗口就立刻失效，不会影响系统里的任何持久配置。这个方式对临时救急来说非常方便，也不需要在别的电脑上留下痕迹。如果你还想更彻底一点，可以关闭当前窗口，用下面这种方式重新打开一个临时放行的 PowerShell：

powershell -ExecutionPolicy Bypass

启动后窗口里的脚本就全部放行了。注意这个Bypass只适合临时跑，日常工作还是建议用规范的RemoteSigned，安全策略该有的底线不能丢。

4.2 Git Bash 才是前端项目的舒适区

很多前端项目在你安装 Git 的时候，会顺带装上 Git Bash，这是一个模拟 Linux 命令行的环境。很多老前端喜欢在 Git Bash 里跑 npm 命令，因为它的命令风格和 mac、Linux 基本一致，也更贴近线上服务器环境。

重要的是，Git Bash 根本不会碰到 PowerShell 脚本执行策略的问题，因为它在自己的 shell 环境里执行的是 npm 的 sh 包装脚本，绕开了 Windows 的 PowerShell 脚本检查。用的时候只需要在项目目录里右键，选择“Git Bash Here”，然后直接npm run dev就能跑。

我自己的开发习惯是：Git Bash 作为主力终端，起码它永远不会因为.ps1问题突然给我颜色看。如果你在 Windows 上被 PowerShell 折腾烦了，可以考虑给 Git Bash 一个机会。

4.3 用 nvm-windows 来管理 Node.js 版本

很多前端开发者的项目不只有一套 Node.js 环境。老项目锁定在 Node 16，新项目要用 Node 20，手动装来装去很容易把 PATH 搞乱，最后npm run dev报的错千奇百怪。我强烈建议 Windows 用户用 nvm-windows 来管理 Node.js 版本，它和 mac/Linux 上的 nvm 是同一套思路，把版本切换做成一条命令。

用 nvm-windows 之后，你不再需要手动去官网下载安装包，也不需要频繁清理 PATH，随时切版本：

nvm install 20.11.0 nvm use 20.11.0

有一点要注意：如果你电脑上已经装过独立的 Node.js，最好先卸载干净，再用 nvm-windows 统一管理。两个版本控制器同时存在，很容易造成 PATH 顺序混乱，最后出现装上去了却不知道跑的是哪个版本的诡异现象。

4.4 顺手把 npm run dev 的其他连环报错一起解决

改了执行策略之后，npm run dev也有可能会撞上新的报错。这里把几个最常见的连带问题一并给你列出来，省得你来回搜索。

第一种是npm ERR! Missing script: "dev"。这是说package.json里的scripts段没有定义dev命令。你可以打开package.json看一眼，确认是不是项目约定用别的命令，比如npm start或npm run serve。

第二种是'vite' 不是内部或外部命令。这种情况多半是依赖没装完整，或者node_modules里某些包已经损坏，直接执行一遍npm install，再跑npm run dev试试。

第三种是EADDRINUSE或者Port 5173 is already in use。这说明端口被占用了，要么关掉占用端口的进程，要么在项目配置里改掉默认端口。Vite 项目可以直接在命令后面追加参数：npm run dev -- --port 5174，或者去vite.config.js里通过server.port配置改默认端口。

5. 实用速查与最终经验

5.1 命令速查表

把这些命令放在一起，方便你直接收藏对照。

5.2 最后分享一点我的实操体会

刚开始学前端那阵子，我第一次看到无法加载文件 npm.ps1也想过卸载重装 Node.js，甚至差点把电脑恢复出厂设置。后来才明白，Windows 上脚本报错，很多时候不是软件装坏了，而是系统自身的脚本防线在起作用。与其一看到报错就重装，不如先花两分钟判断一下问题出在哪个层面：是命令找不到，还是脚本被策略拦截，还是端口被占用。思路捋顺了，大部分问题用一条命令就能解决。

这条报错，本质上是 PowerShell 和 Node.js 工具链之间的一次“方言不通”。你只需要让系统信任本地 npm 脚本，一切就会回到正常轨道。我后来也遇到过无数次类似的错误，但再也没有像第一次那样慌过。希望你今天读完这篇，以后看到.ps1相关的报错，也能直接判断出它是安全策略问题，顺手就化解了。