如何修复 ‘vue cli service 不是可运行的程序’ 报错

在使用 Vue CLI 开发项目时，您可能会遇到一个常见的错误信息：'vue-cli-service' 不是内部或外部命令，也不是可运行的程序或批处理文件（英文通常为 'vue-cli-service' is not recognized as an internal or external command, operable program or batch file）。

这个错误通常意味着您的系统无法找到 vue-cli-service 这个命令。vue-cli-service 是 Vue CLI 的核心执行程序，负责启动开发服务器、构建项目、运行测试等任务。当系统无法找到它时，就无法执行 Vue CLI 相关的操作。

本文将详细介绍导致此错误的常见原因以及相应的解决方案。

常见原因

1. Vue CLI 尚未安装或安装不完整： 这是最直接的原因。如果您的系统中没有安装 Vue CLI，或者安装过程中出现问题，系统自然无法找到 vue-cli-service。
2. Vue CLI 全局安装但未正确配置 PATH 环境变量： 即使您已经全局安装了 Vue CLI，但如果其可执行文件的路径没有被添加到系统的 PATH 环境变量中，命令行也无法识别 vue-cli-service 命令。
3. 在项目内部使用，但未通过 npx 或 npm run 调用： 如果 vue-cli-service 是作为项目依赖（局部安装在 node_modules/.bin 目录下），您不能直接在命令行中输入 vue-cli-service，而需要通过 npx 或 package.json 中定义的脚本来执行。

解决方案

以下是修复此问题的步骤，请按照顺序尝试：

方案一：全局安装 Vue CLI

首先，请确保您的系统上已经安装了 Node.js 和 npm (或 yarn)。然后，尝试全局安装 Vue CLI。

1. 安装 Node.js 和 npm/yarn：
   如果尚未安装，请从 Node.js 官网 下载并安装。npm 会随 Node.js 一同安装。如果您偏好使用 Yarn，可以运行 npm install -g yarn 进行安装。

2. 全局安装 Vue CLI：
   打开您的终端或命令行工具，根据您使用的包管理器执行以下命令：

   • 使用 npm 安装：
     bash
npm install -g @vue/cli

   • 使用 yarn 安装：
     bash
yarn global add @vue/cli

3. 验证安装：
   安装完成后，尝试运行以下命令来验证 Vue CLI 是否成功安装并可执行：
   bash
vue --version
   如果显示 Vue CLI 的版本号，则表示安装成功。此时，您应该可以直接使用 vue create、vue serve 等命令了。
   如果仍然报错，请尝试重启您的终端。

方案二：在项目内部正确使用 vue-cli-service

如果您正在一个 Vue 项目目录中工作，并且该项目是通过 vue create 命令创建的，那么 vue-cli-service 通常会作为项目依赖（即局部依赖）安装在项目的 node_modules 文件夹中。在这种情况下，您应该通过以下方式来运行它：

1. 使用 npx (推荐)：
   npx 是 npm 5.2.0 及更高版本附带的一个工具，它可以执行 node_modules/.bin 目录下的命令，而无需全局安装。在项目根目录下，您可以这样运行 vue-cli-service：
   bash
npx vue-cli-service serve # 启动开发服务器
npx vue-cli-service build # 构建生产版本
npx vue-cli-service lint # 运行代码风格检查
   这是推荐的方法，因为它确保您使用的是项目本地安装的 vue-cli-service 版本，避免了全局版本冲突问题。

2. 通过 package.json 中的脚本：
   Vue CLI 创建的项目通常会在 package.json 文件中定义一些便捷的脚本，例如 serve、build 等。您可以通过 npm run 或 yarn 来运行这些脚本。

   首先，查看您的 package.json 文件，您会看到类似如下的 scripts 部分：
   json
// package.json 示例
{
"name": "my-vue-app",
"version": "0.1.0",
"private": true,
"scripts": {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"lint": "vue-cli-service lint"
},
"dependencies": {
// ...
},
"devDependencies": {
"@vue/cli-service": "~5.0.0", // vue-cli-service 的局部依赖
// ...
}
}
   然后，在项目根目录下，运行对应的脚本：
   “`bash
   npm run serve # 启动开发服务器

   或者

   yarn serve # 如果使用 yarn
   ``
同样地，npm run build或yarn build` 用于构建项目。

方案三：检查并配置系统 PATH 环境变量

如果以上两种方法都未能解决问题，特别是当您确定已经全局安装了 Vue CLI (npm install -g @vue/cli) 但 vue --version 仍然不识别时，很可能是系统 PATH 环境变量配置不正确。

PATH 环境变量告诉操作系统在哪里查找可执行程序。如果 npm 或 yarn 的全局包安装路径不在 PATH 中，系统就无法找到全局安装的命令。

1. 查找 npm 或 yarn 的全局安装路径：
   在终端中运行以下命令来找到全局包的安装目录：

   • npm：
     bash
npm root -g
     此命令会显示全局包的安装路径（例如在 Windows 上可能是 C:\Users\YourUser\AppData\Roaming\npm\node_modules，在 macOS/Linux 上可能是 /usr/local/lib/node_modules）。您需要将这个路径下的 .bin 目录（例如 C:\Users\YourUser\AppData\Roaming\npm 或 /usr/local/bin，具体取决于系统和 Node.js 版本）添加到 PATH。

   • yarn：
     bash
yarn global dir
     此命令会显示 yarn 全局包的安装目录。

2. 手动添加到 PATH 环境变量：
   请注意：修改系统环境变量需要谨慎，错误的修改可能导致系统问题。

   • Windows：

     1. 在搜索栏中输入 “环境变量”，选择 “编辑系统环境变量”。
     2. 在弹出的 “系统属性” 窗口中，点击 “环境变量” 按钮。
     3. 在 “系统变量” 区域找到并选择 “Path” 变量，然后点击 “编辑”。
     4. 点击 “新建”，然后添加您在步骤 1 中找到的 npm 或 yarn 全局 bin 目录的完整路径（例如 C:\Users\YourUser\AppData\Roaming\npm）。
     5. 点击 “确定” 保存所有更改。
     6. 非常重要： 关闭所有当前的命令行窗口，然后重新打开一个新的命令行窗口，以便新的环境变量生效。

   • macOS / Linux：

     1. 打开您的 shell 配置文件。常见的有 ~/.bashrc, ~/.zshrc, ~/.profile。您可以使用 ls -a ~ 查看主目录下的隐藏文件，找到您正在使用的 shell 配置文件。
     2. 使用文本编辑器（如 nano, vim, code 等）打开该文件。
     3. 在文件末尾添加一行，例如：
        bash
export PATH="$PATH:/path/to/npm/global/bin"
        将 /path/to/npm/global/bin 替换为您在步骤 1 中找到的实际路径（例如 /usr/local/bin）。
     4. 保存文件并退出编辑器。
     5. 在终端中运行 source 命令使更改立即生效：
        bash
source ~/.bashrc # 或 ~/.zshrc, ~/.profile
     6. 重启终端，再次尝试运行 vue --version。

总结

通常情况下，解决 'vue cli service 不是可运行的程序' 报错的最简单有效的方法是：

1. 确保全局安装了 Vue CLI： 运行 npm install -g @vue/cli 或 yarn global add @vue/cli。
2. 在项目内部使用 npm run serve (或 yarn serve) 或 npx vue-cli-service serve 来执行命令。

如果上述方法都无效，请仔细检查您的 Node.js、npm/yarn 安装是否正常，并确保系统 PATH 环境变量配置正确。

希望这篇指南能帮助您顺利解决问题，继续您的 Vue 开发之旅！