安装与基本配置

约 900 字大约 3 分钟

2026-01-25

创建 Nuxt 项目

使用官方的脚手架即可创建一个 Nuxt 项目

pnpm

pnpm create nuxt@latest <project-name>

bun

bun create nuxt@latest <project-name>

一个典型的 Nuxt 项目结构如下

hello-nuxt

assets资源目录（参与打包处理，如 scss、图片）

components组件目录（自动导入）

composables组合式 API 目录（自动导入）

layouts布局

middleware路由中间件

serverNitro 服务端路由/API

pages页面目录，基于文件结构自动生成路由

index.vue项目首页

plugins插件目录

public静态资源目录

app.vue应用入口

app.config.ts应用配置（defineAppConfig）

nuxt.config.tsNuxt 框架配置（css、ssr、vite、app、modules 等）

package-lock.json

package.json

README.md

tsconfig.json

package.json 中的命令

build: nuxt build: 生成生产构建产物
dev: nuxt dev: 启动开发服务，支持 HMR 与调试
generate: nuxt generate: 生成静态站点（SSG）产物
preview: nuxt preview: 本地预览生产构建或静态产物
postinstall: nuxt prepare: 生成类型与自动导入

应用入口

在 Nuxt 中 App.vue 会被视为应用的根入口，默认情况下 Nuxt 会为每个路由渲染页面内容，App.vue 通常负责决定页面被包在什么结构里以及入口处要做哪些全局事情

常见用途

使用 NuxtLayout 定义页面布局或自定义布局骨架
使用 NuxtPage 定义路由占位以渲染页面
使用 beforeEach 监听全局路由事件（不推荐，示例用途）
编写全局样式或引入全局样式

如果创建了 App.vue，那么一定要保留 NuxtPage，否则页面不会渲染

<template>
  <NuxtLayout>
    <!-- 页面内容 -> vue-router -->
    <NuxtPage />
  </NuxtLayout>
</template>

<script lang="ts" setup>
const router = useRouter()

router.beforeEach((to, from) => {
  console.log('beforeEach', to, from)
})
</script>

框架配置

框架配置 nuxt.config.ts 位于项目根目录，用于配置框架能力，例如 css、vite、modules 等，具体可以参考: https://nuxt.com/docs/api/configuration/nuxt-config

运行时配置

运行时配置（runtimeConfig）主要用于 "运行时可变" 的配置，可以调用 useRuntimeConfig 来获取运行时信息

重要

服务端可以读取 runtimeConfig 中的全部字段；客户端只能读取 public 下的内容

app.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: 'aabbcc', // 仅服务端
    public: {
      baseURL: 'https://api.example.com',
    },
  },
})

app.vue

<script lang="ts" setup>
const config = useRuntimeConfig()

if (process.server) {
  console.log('API secret:', config.apiSecret)  // apiSecret 仅在 server 端存在
}
</script>

注

在 Nuxt 中，最常用的环境判断是 process.server / process.client
在 Vite 环境中也可以使用 import.meta.server / import.meta.client

应用配置

应用配置（appConfig）用于 "构建时确定" 的公共配置，例如主题、品牌色等，可以调用 useAppConfig 来获取应用配置信息，应用配置可以写在 nuxt.config.ts，也可以独立放在 app.config.ts

app.config.ts

export default defineAppConfig({
  theme: 'light',
})

app.vue

<script lang="ts" setup>
const appConfig = useAppConfig()
</script>

在 env 定义环境变量

Nuxt 会读取项目根目录的 .env 文件，因此可以把环境变量放在这些文件里。这些环境变量可按不同环境被拆分：.env、.env.local、.env.development、.env.production 等

提示

.env 文件不会被打包进客户端代码，但 NUXT_PUBLIC_ 前缀的变量会暴露给浏览器，所以需要避免存放敏感信息

# .env
NUXT_API_SECRET=server_secret
NUXT_PUBLIC_BASE_URL=https://api.example.com

对应规则

NUXT_ 前缀：写入 runtimeConfig
NUXT_PUBLIC_ 前缀：写入 runtimeConfig.public

基本语法

基础篇

原理篇