超详细 Vue CLI 移动端预览插件实战：支持本地/TPGZ/NPM/Git 多场景使用（小白零基础入门）

摘要

你是否还在为「移动端如何快速预览本地 Vue 开发项目」而烦恼？手动查找局域网 IP、输入端口号繁琐又容易出错？本文将围绕「实现移动端便捷预览本地服务项目」这一核心需求，手把手教你开发一款 Vue CLI 专属二维码插件。插件不仅能自动生成移动端可扫码的二维码，还完美支持本地调试、TGZ 压缩包、NPM 公开包、Git 仓库四种使用场景，同时附带解决插件开发中「二维码输出时机」的常见问题，代码可直接复制，小白也能轻松上手！

一、前言

在 Vue 项目开发过程中，「移动端预览本地服务」是高频刚需：开发者需要在手机上验证页面适配、交互效果等，但传统方式需要手动查询电脑局域网 IP、记录项目端口，再在手机浏览器中输入地址，步骤繁琐且容易出错（如 IP 输入错误、端口冲突等）。

本文的核心目标是：开发一款 Vue CLI 插件，通过「自动生成可视化二维码」的方式，让手机扫码即可快速访问本地 Vue 服务，同时支持本地调试、TGZ 包、NPM 包、Git 包四种使用场景，满足个人开发、团队协作、全网复用等不同需求，同时解决开发过程中「二维码输出时机」的常见问题。

二、核心需求与插件优势

1. 核心需求

核心功能：自动获取电脑局域网 IP + 项目端口，生成移动端可扫码的二维码，扫码即可访问本地 Vue 服务；
多场景使用：支持本地调试（未发布插件）、TGZ 压缩包（私有部署）、NPM 公开包（全网复用）、Git 仓库（团队协作）四种引入方式；
兼容性强：支持 Vue 2/Vue 3 项目，适配 Vue CLI 3+ 所有版本；
无需手动配置：插件自动开启局域网访问，无需用户修改 vue.config.js；
细节优化：解决二维码输出时机问题，确保使用体验流畅，避免日志混乱或输出过晚。

2. 插件核心优势

优势点	具体说明
便捷性	扫码访问，无需手动输入 IP + 端口，零出错
多场景兼容	支持本地/TPGZ/NPM/Git 四种使用方式
无侵入性	不修改项目原有代码，卸载后无残留
自动配置	自动开启 `host: 0.0.0.0`，支持局域网访问
细节优化	解决二维码输出时机问题，日志整洁美观

三、第一步：插件开发（核心功能实现，支持移动端扫码预览）

1. 插件目录规范（Vue CLI 要求，必须遵守）

Vue CLI 插件必须以 vue-cli-plugin-xxx 命名，否则无法被项目自动识别，执行命令创建目录：

bash 复制代码

# 创建插件目录并进入（小白直接复制终端执行）
mkdir vue-cli-plugin-vue-mobile-preview && cd vue-cli-plugin-vue-mobile-preview

2. 初始化 package.json（配置插件信息与依赖）

在插件目录下执行 npm init -y 快速生成配置文件，再手动替换为以下内容（确保依赖与兼容性）：

json 复制代码

{
  "name": "vue-cli-plugin-vue-mobile-preview",
  "version": "1.0.0",
  "description": "Vue CLI 3+ 插件：自动生成二维码，支持移动端扫码预览本地Vue服务，兼容本地/TGZ/NPM/Git多场景",
  "main": "index.js",
  "keywords": [
    "vue",
    "vue-cli",
    "mobile preview",
    "qrcode",
    "local service",
    "TGZ",
    "NPM",
    "Git"
  ],
  "dependencies": {
    "qrcode": "^1.5.3" // 核心依赖：用于生成终端可视化二维码
  },
  "peerDependencies": {
    "@vue/cli-service": ">=3.0.0" // 兼容 Vue CLI 3+ 所有版本
  },
  "author": "你的姓名",
  "license": "MIT"
}

关键说明：dependencies 中声明 qrcode 依赖，用户安装插件后无需手动安装；peerDependencies 确保插件与 Vue CLI 版本兼容。

3. 编写核心 index.js（实现移动端扫码预览核心功能）

这是插件的核心文件，实现「自动获取局域网 IP + 项目端口 + 生成二维码」的核心功能，同时解决「二维码输出时机」问题，代码含详细注释，小白可直接复制：

javascript 复制代码

// 引入核心依赖
const QRCode = require('qrcode');
const os = require('os'); // Node.js 原生模块，无需额外安装，用于获取局域网IP

/**
 * 核心功能1：自动获取本机局域网 IPv4 地址（移动端访问需要该 IP）
 * @returns {string} 有效局域网IP | 兜底本地回环地址（127.0.0.1）
 */
function getLocalLanIp() {
  const networkInterfaces = os.networkInterfaces();
  // 遍历所有网卡接口，筛选符合条件的局域网 IP
  for (const ifaceName in networkInterfaces) {
    const ifaceList = networkInterfaces[ifaceName];
    for (const iface of ifaceList) {
      // 过滤条件：IPv4 协议、非本地回环地址、非虚拟内网地址
      if (iface.family === 'IPv4' && !iface.internal && iface.address !== '127.0.0.1') {
        return iface.address; // 返回有效局域网 IP
      }
    }
  }
  // 兜底：未获取到局域网 IP 时，返回本地回环地址（仅本机可访问，移动端无法扫码）
  return '127.0.0.1';
}

/**
 * 核心功能2：生成并打印移动端可扫码的二维码（核心逻辑）
 * @param {string} lanIp 局域网 IP
 * @param {number} port 项目端口
 */
function printMobileQrcode(lanIp, port) {
  // 构造移动端访问地址（核心：局域网 IP + 项目端口，手机扫码即可访问）
  const mobileAccessUrl = `http://${lanIp}:${port}`;
  // 构造本机访问地址（用于提示开发者）
  const localAccessUrl = `http://localhost:${port}`;

  // 打印醒目提示信息，区分日志层级
  console.log('\n=====================================================');
  console.log('🎉 [vue-cli-plugin-vue-mobile-preview] 移动端预览二维码已生成！');
  console.log(`🔧  本机访问地址：${localAccessUrl}`);
  console.log(`🌐  移动端访问地址：${mobileAccessUrl}`);
  console.log('📱  扫码提示：手机与电脑连接同一 WiFi，打开相机/微信扫一扫即可预览！\n');

  // 生成终端可视化二维码
  QRCode.toString(mobileAccessUrl, {
    type: 'terminal', // 输出到终端
    margin: 1, // 二维码边距（紧凑美观）
    small: false // 显示大尺寸二维码，提高手机扫码成功率
  }, (err, qrCodeStr) => {
    if (!err) {
      console.log(qrCodeStr); // 打印二维码
    } else {
      // 异常捕获：二维码生成失败时，输出错误信息但不影响项目运行
      console.error('❌ 二维码生成失败：', err.message);
      console.log('💡 替代方案：手动在手机浏览器输入地址 -> ', mobileAccessUrl);
    }
    console.log('=====================================================\n');
  });
}

/**
 * 辅助变量：标记是否已打印二维码（避免热更新时重复输出）
 */
let hasPrintQrcode = false;

/**
 * Vue CLI 插件核心导出函数（入口逻辑）
 * @param {Object} api Vue CLI 核心 API
 * @param {Object} options 项目的 vue.config.js 配置项
 */
module.exports = (api, options) => {
  api.chainWebpack((config) => {
    // 核心配置：强制设置 host: 0.0.0.0，允许局域网设备（手机）访问本地服务
    // 无需用户手动修改 vue.config.js，插件自动配置
    config.devServer.host('0.0.0.0');

    // 解决二维码输出时机问题：使用 compiler.hooks.done 事件（项目完全就绪后输出，避免日志混乱）
    // 这是插件开发中的细节优化，不影响核心的移动端预览功能
    config.plugin('mobile-preview-qrcode-plugin').use(class MobilePreviewPlugin {
      apply(compiler) {
        // compiler.hooks.done：Webpack 编译（首次构建/热更新）完成后触发
        compiler.hooks.done.tap('MobilePreviewPlugin', () => {
          // 仅在首次构建完成后打印一次二维码，避免热更新时重复输出
          if (hasPrintQrcode) {
            return;
          }

          // 获取项目端口（优先使用用户自定义端口，默认 8080）
          const devServerConfig = options.devServer || {};
          const projectPort = devServerConfig.port || 8080;
          // 获取局域网 IP
          const localLanIp = getLocalLanIp();
          // 生成并打印移动端预览二维码
          printMobileQrcode(localLanIp, projectPort);

          // 标记已打印二维码
          hasPrintQrcode = true;
        });
      }
    });
  });
};

4. 插件最终目录结构（小白核对，确保无误）

插件目录仅需 2 个核心文件，简洁易维护，结构如下：

bash 复制代码

vue-cli-plugin-vue-mobile-preview/
├── index.js       # 核心逻辑文件（实现移动端扫码预览+时机优化）
└── package.json   # 插件配置文件（依赖+兼容性配置）

四、第二步：多场景使用教程（核心重点，覆盖所有使用场景）

插件开发完成后，支持 4 种使用场景，满足不同开发需求（个人调试、团队协作、全网复用等），步骤详细，小白可按需选择。

场景1：本地调试（个人开发，未发布插件，快速验证功能）

适用于插件开发完成后，个人在本地 Vue 项目中验证功能，无需发布到任何仓库。

前置准备

插件目录与目标 Vue 项目同级（方便关联），目录结构示例：

perl 复制代码

├── vue-cli-plugin-vue-mobile-preview/  # 插件目录
└── my-vue-project/                # 目标 Vue 项目（需要移动端预览的项目）
    ├── src/
    ├── package.json
    └── ... 其他项目文件

操作步骤

进入目标 Vue 项目根目录，执行以下命令关联本地插件：

bash 复制代码

# npm 命令（兼容所有环境，推荐小白使用）
npm install file:../vue-cli-plugin-vue-mobile-preview --save-dev

# 若使用 pnpm，执行此命令
# pnpm add file:../vue-cli-plugin-vue-mobile-preview -D

# 若使用 yarn，执行此命令
# yarn add file:../vue-cli-plugin-vue-mobile-preview --dev

路径说明：../vue-cli-plugin-vue-mobile-preview 是插件的相对路径，若目录层级不同可调整（如 ../../xxx）。

验证插件安装成功：查看目标项目的 package.json 文件，若 devDependencies 中出现以下配置，说明关联成功：
json 复制代码
```
"devDependencies": {
  "vue-cli-plugin-vue-mobile-preview": "file:../vue-cli-plugin-vue-mobile-preview"
}
```
启动项目，验证移动端预览功能：在目标项目根目录执行启动命令：
bash 复制代码
```
# Vue CLI 3+ 通用命令
npm run serve

# 兼容命令：npm run dev（部分项目配置别名）
```
移动端扫码预览：
- 终端最后会输出二维码（带醒目提示）；
- 确保手机与电脑连接同一 WiFi（同一局域网）；
- 打开手机相机/微信/支付宝「扫一扫」，扫描终端二维码，即可快速预览本地 Vue 项目。

本地插件卸载（若无需使用）：

bash 复制代码

# npm 命令
npm uninstall vue-cli-plugin-vue-mobile-preview

# pnpm/yarn 命令对应：pnpm remove / yarn remove

场景2：TGZ 压缩包使用（私有部署，团队内部复用，无需发布 NPM）

适用于插件无需公开，仅在公司/团队内部复用，可上传到私有服务器或共享文件夹供团队成员使用。

操作步骤

插件打包为 TGZ 压缩包：进入插件目录，执行以下命令打包：
bash 复制代码
```
# 进入插件目录
cd vue-cli-plugin-vue-mobile-preview

# 打包生成 TGZ 压缩包（npm pack 是 npm 原生命令，无需额外安装工具）
npm pack
```
- 打包成功后，插件目录同级会生成 vue-cli-plugin-vue-mobile-preview-1.0.0.tgz 文件（文件名格式：插件名称+版本号）；
- 该压缩包包含插件所有核心文件，可直接用于安装。
分发 TGZ 压缩包：将生成的 TGZ 文件分发到团队成员（如上传到公司私有服务器、共享网盘、GitLab 私有仓库附件等），获取可访问的路径/地址（示例）：
- 本地共享：/Users/xxx/Shared/vue-cli-plugin-vue-mobile-preview-1.0.0.tgz
- 私有服务器：https://xxx.company.com/plugins/vue-cli-plugin-vue-mobile-preview-1.0.0.tgz

项目中安装 TGZ 插件：进入目标 Vue 项目根目录，执行以下命令安装（根据 TGZ 地址类型选择）：

bash 复制代码

# 方式1：安装本地/共享文件夹中的 TGZ 包
npm install file:/Users/xxx/Shared/vue-cli-plugin-vue-mobile-preview-1.0.0.tgz --save-dev

# 方式2：安装私有服务器上的 TGZ 包（HTTPS 地址）
npm install https://xxx.company.com/plugins/vue-cli-plugin-vue-mobile-preview-1.0.0.tgz --save-dev

# pnpm/yarn 命令兼容，只需替换 npm install 为 pnpm add / yarn add

验证移动端预览功能：执行 npm run serve 启动项目，后续步骤同「本地调试」，手机扫码即可预览。

场景3：NPM 公开包使用（全网复用，开源共享）

适用于插件功能成熟，需要公开给全网开发者使用，发布到 npm 公开仓库。

操作步骤

前置准备：
- 拥有 npm 账号（未注册可前往 npm 官网注册）；
- 切换到 npm 官方源（若配置了国内镜像源，小白执行以下命令）：
bash 复制代码
```
npm config set registry https://registry.npmjs.org/
```
登录 npm 账号：进入插件目录，执行登录命令，按提示输入用户名、密码、邮箱：
bash 复制代码
```
# 进入插件目录
cd vue-cli-plugin-vue-mobile-preview

# 登录 npm 账号
npm login
```
发布插件到 npm 公开仓库：在插件目录下执行发布命令，无需额外配置：
bash 复制代码
```
npm publish
```
- 发布失败排查：若提示包名重复，修改 package.json 中的 name 字段；若提示版本重复，修改 version 字段（如从 1.0.0 改为 1.0.1）。

项目中安装 NPM 插件：在任意 Vue CLI 3+ 项目根目录，执行以下命令即可安装（全网开发者均可使用）：

bash 复制代码

# 方式1：npm 命令（推荐）
npm install vue-cli-plugin-vue-mobile-preview --save-dev

# 方式2：Vue CLI 专属快捷命令（自动识别插件，无需加 --save-dev）
vue add vue-mobile-preview

# pnpm/yarn 命令兼容
# pnpm add vue-cli-plugin-vue-mobile-preview -D
# yarn add vue-cli-plugin-vue-mobile-preview --dev

验证移动端预览功能：执行 npm run serve 启动项目，手机扫码即可预览本地 Vue 项目。

场景4：Git 仓库使用（团队协作，无需发布 NPM，支持版本控制）

适用于插件托管在 Git 仓库（GitHub/Gitee/GitLab），团队成员可直接通过 Git 地址安装，支持版本控制和代码同步。

操作步骤

插件目录初始化 Git 仓库：进入插件目录，执行以下命令初始化并提交代码：

bash 复制代码

# 进入插件目录
cd vue-cli-plugin-vue-mobile-preview

# 初始化 Git 仓库
git init

# 添加所有文件
git add .

# 提交代码
git commit -m "init: 完成移动端预览插件开发，支持扫码访问"

推送插件到线上 Git 仓库：在 GitHub/Gitee/GitLab 上创建一个新仓库，然后将本地插件代码推送上去（以 GitHub 为例）：

bash 复制代码

# 关联线上 Git 仓库（替换为你的仓库地址）
git remote add origin https://github.com/你的用户名/vue-cli-plugin-vue-mobile-preview.git

# 推送代码到 master/main 分支
git push -u origin master

项目中通过 Git 地址安装插件：进入目标 Vue 项目根目录，执行以下命令安装（支持 HTTPS/SSH 两种地址格式）：

bash 复制代码

# 方式1：HTTPS 地址（无需配置密钥，小白推荐使用，公开/私有仓库均可）
npm install https://github.com/你的用户名/vue-cli-plugin-vue-mobile-preview.git --save-dev

# 方式2：SSH 地址（需配置 Git 密钥，推荐团队私有仓库使用）
npm install git+ssh://git@github.com/你的用户名/vue-cli-plugin-vue-mobile-preview.git --save-dev

# 方式3：GitHub 专属简化格式（自动识别）
npm install 你的用户名/vue-cli-plugin-vue-mobile-preview --save-dev

# pnpm/yarn 命令兼容

验证移动端预览功能：执行 npm run serve 启动项目，手机扫码即可预览本地 Vue 项目，同时可通过 Git 仓库实现插件版本更新和团队同步。

五、插件开发细节优化（解决二维码输出时机问题）

这是插件开发过程中的常见问题，不影响核心的移动端预览功能，但可优化使用体验，小白可直接复用代码，无需深入理解。

1. 问题描述

若使用 devServer.after 钩子输出二维码，会出现「二维码输出后还有 Webpack 编译日志」的问题，导致日志混乱；若提前输出，会被构建日志覆盖，影响扫码体验。

2. 解决方案

使用 compiler.hooks.done 事件，在 Webpack 编译（首次构建）完成后输出二维码，同时添加 hasPrintQrcode 标记，避免热更新时重复输出，代码已集成在插件核心 index.js 中，无需额外修改。

3. 优化效果

二维码在项目完全就绪后输出，日志整洁美观，无多余信息干扰；
仅输出一次二维码，避免热更新时重复打印，提升使用体验。

六、常见问题排查（小白避坑指南）

1. 移动端扫码无法访问本地项目

排查1：手机与电脑是否连接同一 WiFi（同一局域网）；
排查2：电脑防火墙是否关闭（防火墙可能拦截手机的访问请求）；
排查3：项目端口是否被占用（更换端口后重新启动项目，如在 vue.config.js 中配置 devServer.port: 8081）；
排查4：插件是否自动配置 host: 0.0.0.0（本文插件已自动配置，无需手动修改）。

2. 插件安装后无二维码输出

排查1：插件名称是否以 vue-cli-plugin- 开头（Vue CLI 仅自动识别该前缀）；
排查2：是否重启项目（插件安装后需重启项目才能生效）；
排查3：目标项目 package.json 中是否存在插件依赖（确认安装成功）；
排查4：是否安装 qrcode 依赖（插件已声明依赖，若缺失可手动执行 npm install qrcode --save-dev）。

3. 二维码重复输出（热更新时）

排查：是否添加 hasPrintQrcode 标记（本文插件已添加，无需额外修改）。

4. TGZ/Git 插件安装失败

排查1：地址是否正确（TGZ 地址需指向 .tgz 文件，Git 地址需带 .git 后缀）；
排查2：网络是否通畅（私有服务器/Git 仓库是否可正常访问）；
排查3：包管理器版本是否兼容（建议使用 npm 8+ / pnpm 6+ / yarn 1+）。

七、总结

核心目标达成：本文围绕「移动端便捷预览本地 Vue 服务项目」这一核心需求，开发了一款 Vue CLI 插件，实现了「自动生成二维码 + 扫码快速访问」的核心功能，解决了手动输入 IP + 端口的繁琐问题；
多场景全覆盖：详细讲解了插件的 4 种使用场景（本地调试、TGZ 压缩包、NPM 公开包、Git 仓库），满足个人开发、团队协作、全网复用等不同需求；
小白友好：所有代码可直接复制，步骤详细无遗漏，无需复杂配置，同时提供常见问题排查指南，降低上手门槛；
细节优化到位：附带解决插件开发中「二维码输出时机」的问题，优化使用体验，确保日志整洁、无重复输出；
兼容性强：支持 Vue 2/Vue 3 项目，适配 Vue CLI 3+ 所有版本，无侵入性，卸载后无残留。

通过本文，小白也能轻松开发并使用 Vue CLI 移动端预览插件，实现多场景下的移动端便捷预览，提升 Vue 项目开发效率！