文章目录
📌 摘要
在使用 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 仓库) | ⚠️ 进阶推荐 | 适合团队统一开发规范 |
✅ 总结
本文详细记录了在使用 vue init webpack project
初始化 Vue 项目时,遇到卡在 downloading template
的问题,并分析其根本原因是 GitHub 访问异常 或 网络连接问题。
提供的解决方案包括:
- 检查本地网络与 GitHub 的连接状态;
- 改用更现代的项目初始化方式,如
npm create vue@latest
; - 使用
vue create
替代vue init
。
对于初学者和 Vue 开发者来说,掌握这些技巧有助于避免在项目搭建阶段浪费大量时间。
📌 如果你觉得这篇文章对你有帮助,请点赞 + 收藏 + 分享,让更多人了解如何解决 Vue CLI 初始化模板卡顿问题!
💬 欢迎留言讨论你在使用 Vue CLI 或其他脚手架工具时遇到的类似问题。