前端解决无法创建Nuxt3项目！

问题:npm create nuxt 老是失败

新人创建 Nuxt 3 项目时常踩的坑:npm create nuxt-app@latest 或 npx nuxi init my-app 执行到一半卡住,或者直接报 fetch failed。原因基本是从 GitHub 拉模板时被卡了(raw.githubusercontent.com 国内访问不稳)。

方案 1:用 ghproxy 加速

Nuxi 内部用 giget 拉模板,可以设置 GitHub 加速代理:

# 临时
GIGET_GITHUB_URL=https://ghproxy.com/https://github.com npx nuxi init my-app

# 永久(放进 .bashrc / .zshrc)
export GIGET_GITHUB_URL=https://ghproxy.com/https://github.com

Windows PowerShell:

$env:GIGET_GITHUB_URL = "https://ghproxy.com/https://github.com"
npx nuxi init my-app

这样会把 GitHub 仓库 URL 自动改写成加速代理域名。giget 文档里有完整变量列表。

方案 2:用本站打包好的纯净模板

如果代理也不稳,直接下载我打包好的纯净 Nuxt 3 项目模板(已经 npm install 过一次,带 node_modules,解压就能跑):

下载后进入目录,装依赖:

npm i

启动开发服务器:

npm run dev

访问 http://localhost:3000 就能看到默认页面了。

方案 3:手动从 GitHub clone 模板

如果你科学上网畅通,绕开脚手架,直接 clone 官方模板仓库:

# 克隆官方 starter
git clone https://github.com/nuxt/starter --branch v3 my-nuxt-app
cd my-nuxt-app
rm -rf .git

# 装依赖
npm install   # 或 pnpm install / yarn

# 启动
npm run dev

这个方式好处:完全不依赖 Nuxi CLI 内部的网络逻辑,只用 git 和 npm,可控性最高。

方案 4:换镜像源

有时候卡的不是 GitHub 拉模板,而是 npm install 阶段去 npm registry 下载几十 MB 包慢。先把 npm 源换成淘宝:

npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 应输出 https://registry.npmmirror.com/

或者用 nrm 切换工具:

npm i -g nrm
nrm ls          # 列出可用源
nrm use taobao  # 切到淘宝

方案 5:用 pnpm + 镜像

pnpm 速度比 npm 快不少(硬链接复用),配合镜像:

npm i -g pnpm
pnpm config set registry https://registry.npmmirror.com
pnpm create nuxt@latest my-app

排错快速 checklist

• 报 fetch failed / ENOTFOUND → 网络问题,试 GitHub 代理或换网络
• 报 EACCES permission denied → 不要用 sudo,改 npm 的全局目录,或者用 nvm 装 Node
• 装到一半提示 esbuild 下载失败 → esbuild 二进制下载慢,设环境变量 ESBUILD_BINARY_PATH 或换镜像
• 装完 npm run dev 报 Cannot find module → node_modules 没装全,删了重装
• 启动后页面白屏 / 报 404 → 删除 .nuxt、node_modules、package-lock.json,重装

顺便:Nuxt 3 项目结构速览

刚搭好的 Nuxt 3 项目长这样:

my-nuxt-app/
├── app.vue              # 应用入口组件
├── nuxt.config.ts       # Nuxt 配置
├── package.json
├── pages/               # 自动路由(文件即路由)
│   └── index.vue
├── components/          # 自动注册的组件
├── composables/         # 自动注册的 composable
├── public/              # 静态资源,直接映射到 /
├── server/              # 服务端 API + middleware
│   └── api/
├── plugins/             # 客户端 / 服务端插件
├── middleware/          # 路由中间件
└── assets/              # 需要打包处理的资源(less/sass/图片)

对照这个目录,Nuxt 3 大部分目录是"约定优于配置",不用手动配 router、不用手动注册组件,熟悉后开发速度非常快。

—— 别看了 · 2026