【学习记录】Vue CLI 初始化项目卡在 downloading template 的解决方法

原创已于 2025-06-02 23:56:40 修改 · 2.6k 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#vue #npm #学习

于 2022-04-23 21:50:07 首次发布

学习记录专栏收录该内容

26 篇文章

订阅专栏

文章目录

📌 摘要

在使用 Vue CLI 命令 vue init webpack project-name 创建项目时，很多用户会遇到命令执行后长时间卡在 downloading template 状态的问题。本文基于一次真实开发场景，分析该问题产生的根本原因，并提供有效的解决方法，帮助开发者快速完成 Vue 项目的初始化。

⚠️ 问题描述

在终端中执行以下命令创建 Vue 项目时：

vue init webpack my-project

命令行界面一直停留在如下提示，无任何进展：

> vue init webpack my-project

  vue-cli · [webpack] Still downloading template...

即使多次切换网络环境（如 WiFi、热点等），问题依然存在。

🔍 原因分析

经过排查发现，vue init 命令背后实际上是从 GitHub 上拉取官方模板仓库（默认是 https://github.com/vuejs-templates/webpack）。如果由于网络原因无法访问 GitHub，则会导致模板下载失败或卡住。

常见的原因包括：

原因	说明
GitHub 访问异常	本地网络与 GitHub 之间的连接不稳定或被限制
DNS 解析问题	导致无法解析 github.com 域名
网络不稳定	下载中断或速度过慢
Vue CLI 默认源在国外	未配置国内镜像

✅ 解决方案

✅ 方法一：检查网络与 GitHub 连接状态

首先确认是否能够正常访问 GitHub 官网。如果无法访问，可以通过以下步骤尝试解决问题：

检查本地 DNS 设置：有时 DNS 配置不当可能导致无法解析 github.com 域名。

你可以通过手动修改 hosts 文件的方式，添加 GitHub 的 IP 地址来绕过默认的 DNS 解析。例如：
```
140.82.112.3 github.com
```
💡 提示：由于 GitHub 的 IP 地址可能会发生变化，建议使用在线工具如 IP Address Location 查询当前 github.com 对应的最新 IP 地址。

在该网站中输入 github.com，即可获取当前域名对应的 IP 列表，选择一个稳定的地址写入你的 hosts 文件。
重启网络设备：有时简单的重启路由器或交换机可以解决临时的网络连接问题。
使用国内镜像加速 npm 安装：虽然不能完全绕过 GitHub 模板下载，但可以提升 npm 包的安装速度。
```
npm config set registry https://registry.npmmirror.com
```

✅ 方法二：使用 `create-vue` + Vite（推荐现代方式）

如果你不想依赖 GitHub 模板下载机制，可以改用更现代的 Vue 官方脚手架工具：

使用 `npm create vue@latest` 创建项目（Vue 3 推荐）：

npm create vue@latest

然后按照提示输入项目名称和配置项，无需等待模板下载，过程更稳定快捷。

✅ 方法三：使用淘宝 NPM 镜像（临时替代）

你可以通过配置 npm 镜像来加速模板下载：

npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g @vue/cli

不过注意：这种方式并不能完全绕过 GitHub 下载模板的过程。

🛠️ 扩展建议：替代方案推荐

工具	是否推荐	说明
`vue create`（Vue CLI 3+）	✅ 推荐	图形化交互式创建项目，不依赖 GitHub 模板
`vite create`（Vue 3 推荐）	✅ 强烈推荐	更快、更现代，零配置启动项目
自定义模板（私有 Git 仓库）	⚠️ 进阶推荐	适合团队统一开发规范