webpackdevserver不是不内部或内部或外部命令

昨天下午，同事老张盯着终端屏幕，外部脸都快贴到显示器上了。命令他刚拉下项目代码，不内部或运行 npm run dev，外部结果蹦出一行红字：'webpack-dev-server' 不是命令内部或外部命令，也不是不内部或可运行的程序或批处理文件。老张挠头，外部说昨天还好好的命令，今天就翻脸了。不内部或我凑过去一看，外部心里大概有数了——八成是命令依赖没装全，或者版本对不上。不内部或

这种报错太常见了。外部它不复杂，命令但特别容易让人火大，因为错误提示根本不告诉你“为什么”，只告诉你“不行”。你检查了 webpack.config.js，没问题；你确认了 package.json 里的脚本，也没毛病。那问题出在哪？

核心原因几乎总是这几个：第一，你根本没安装 webpack-dev-server，或者它没被装进 node_modules。第二，你全局装了，但项目里没装，而 npm run 执行脚本时，找的是项目本地依赖，不是全局。第三，你换了电脑或者换了分支，package-lock.json 和实际安装的依赖对不上，导致某些包被跳过了。

最坑的是第二种情况。很多人习惯 npm install -g webpack-dev-server，然后跑项目发现还是报错。为什么？因为 npm run 脚本会把 node_modules/.bin 加到系统的 PATH 环境变量里，但仅限项目内部。你全局安装的包，不在那个路径下，系统自然找不到。这就像你带了把钥匙，但门锁是另一把钥匙才能开的——不是钥匙不对，是门不认你。

解决方式也简单。先别急着百度，打开终端，在项目根目录跑一下 npm install，看有没有报错。如果安装过程顺利，再试试 npx webpack-dev-server。npx 会临时去 node_modules/.bin 里找命令，找不到才去全局找，它比直接敲命令更聪明。如果 npx 能跑起来，说明依赖其实装了，只是脚本路径有问题——检查 package.json 里的 scripts 是不是写错了，比如把 webpack-dev-server 拼成了 webpackserver。

还有一种情况，发生在用 npm 7 以上版本的时候。npm 的依赖解析策略变了，如果 webpack-dev-server 是作为某个插件的依赖被间接安装的，它可能不会出现在顶层 node_modules 里，导致脚本找不到。这时候别硬装，先删掉 node_modules 和 package-lock.json，重新 npm install，大概率能解决。这个过程大概几分钟，但比你在网上翻帖子强。

老张后来怎么解决的？我让他删了 node_modules 重装，装完就好了。他问我为什么昨天还好好的——因为昨天他同事往 package.json 里加了新依赖，但没提交 lock 文件，他拉代码后 npm 自动更新了部分依赖，把 webpack-dev-server 给顶掉了。这种事在团队协作里太常见了，代码能跑的时候没人动依赖，一跑不起来就互相甩锅。

最后说个冷知识：这个报错不是 Windows 专属。Mac 和 Linux 上也会遇到，只是提示措辞不同，比如 command not found。本质一样，都是 PATH 找不到执行文件。所以别一看到“不是内部或外部命令”就觉得是系统问题——先查依赖，再查脚本，最后查环境变量。按这个顺序排查，五分钟内基本能定位。