Get Started

注

Nuxt 是一个免费的开源框架，以直观且可扩展的方式使用 Vue.js 创建类型安全、高性能和生产级的全栈 Web 应用程序和网站。

安装

使用 Nuxt 的脚手架工具 nuxi 初始化项目

pnpm

pnpm dlx nuxi@latest init <project-name>

配置

环境覆盖

可以在 nuxt.config 中配置完全类型化的环境覆盖。

nuxt.config.ts

export default defineNuxtConfig({
  $production: {
    routeRules: {
      "/**": { isr: true },
    },
  },
  $development: {
    //
  },
  $env: {
    staging: {
      //
    },
  },
});

要在运行 Nuxt CLI 命令时选择环境，只需将名称传递给 --envName 标志

如： nuxi build --envName staging

环境变量

runtimeConfig API 向您应用程序的其余部分暴露环境变量等值。默认情况下，这些键仅在服务器端可用。 runtimeConfig.public 中的键在客户端也可用。

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    // 仅在服务器端可用的私有键
    apiSecret: "123",
    // public 中的键也在客户端暴露
    public: {
      apiBase: "/api",
    },
  },
});

.env

# 这将覆盖 apiSecret 的值
NUXT_API_SECRET=api_secret_token

这些变量利用 useRuntimeConfig() 可组合函数暴露给您应用程序的其余部分。

应用程序变量

app.config.ts 文件位于源目录中（默认是项目的根目录），用于暴露可以在构建时确定的公共变量。与 runtimeConfig 选项相反，这些变量不能通过环境变量覆盖。

app.config.ts

export default defineAppConfig({
  title: "Hello Nuxt",
  theme: {
    dark: true,
    colors: {
      primary: "#ff0000",
    },
  },
});

这些变量利用 useAppConfig 可组合函数暴露给您应用程序的其余部分。

视图 Views

Nuxt 提供多个组件层来实现应用程序的用户界面。

入口点 app.vue

默认情况下，Nuxt 将把这个文件视为入口点，并在应用程序的每个路由中渲染其内容。

app.vue

<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

组件 components

大多数组件是可重用的用户界面部分，例如按钮和菜单。在 Nuxt 中，您可以在 components/ 目录中创建这些组件，它们将自动在您的应用程序中可用，而无需显式导入它们。

页面 pages

页面表示每个特定路由模式的视图。 pages/ 目录中的每个文件表示一个不同的路由，显示其内容。

要使用页面，创建 pages/index.vue 文件，并将 <NuxtPage /> 组件添加到 app.vue。您现在可以通过在 pages/ 目录中添加新文件来创建更多页面及其相应的路由。

pages/index.vue

<template>
  <div>
    <h1>欢迎来到首页</h1>
    <AppAlert> 这是一个自动导入的组件 </AppAlert>
  </div>
</template>

pages/about.vue

<template>
  <section>
    <p>此页面将在 /about 路由中显示。</p>
  </section>
</template>

布局 layouts

布局是页面的包装，其中包含多个页面的通用用户界面，例如标题和页脚显示。布局是使用 <slot /> 组件显示页面内容的 Vue 文件。 layouts/default.vue 文件将作为默认文件使用。自定义布局可以作为您页面元数据的一部分进行设置。

app.vue

<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

layouts/default.vue

<template>
  <div>
    <AppHeader />
    <slot />
    <AppFooter />
  </div>
</template>

pages/index.vue

<template>
  <div>
    <h1>欢迎来到首页</h1>
    <AppAlert> 这是一个自动导入的组件 </AppAlert>
  </div>
</template>

pages/about.vue

<template>
  <section>
    <p>此页面将在 /about 路由中显示。</p>
  </section>
</template>

高级扩展

可以通过添加一个 Nitro 插件 (服务器插件) 来实现对 HTML 模板的完全控制，该插件注册了一个钩子。 render:html 钩子的回调函数允许您在将 HTML 发送给客户端之前进行修改。

server/plugins/extend-html.ts

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook("render:html", (html, { event }) => {
    // 这将是 html 模板的对象表示。
    console.log(html);
    html.head.push(`<meta name="description" content="我的自定义描述" />`);
  });
  // 您也可以在这里拦截响应。
  nitroApp.hooks.hook("render:response", (response, { event }) => {
    console.log(response);
  });
});

资源

Nuxt 提供了两种处理资源的选项。

public/ 目录中的内容会原样提供在服务器根目录下。
assets/ 目录按惯例包含所有希望构建工具（Vite 或 webpack）处理的资源。

样式

本地样式表

将 CSS 文件放在 assets/ 目录中，并在 Vue 组件中导入它们。也可使用 sass 等预处理器。样式表会内联在 Nuxt 渲染的 HTML 中。

pages/index.vue

<script>
// 使用静态导入以兼容服务端
import "~/assets/css/first.css";

// 注意：动态导入在服务端不兼容
import("~/assets/css/first.css");
</script>

<style>
@import url("~/assets/css/second.css");
</style>

全局样式表

在 Nuxt 配置中使用 css 属性。样式表的自然位置是 assets/ 目录。然后您可以引用其路径，Nuxt 会将其包含在您的应用程序的所有页面中。

nuxt.config.ts

export default defineNuxtConfig({
  css: ["~/assets/css/main.css"],
});

处理全局样式变量

如果您需要在预处理文件中注入代码，例如带有颜色变量的 sass partial，您可以通过 vite preprocessors options 来做到。

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@use "~/assets/_colors.scss" as *;',
        },
      },
    },
  },
});

使用 `v-bind` 绑定动态样式

您可以使用 v-bind 函数在样式块中引用 JavaScript 变量和表达式。绑定将是动态的，这意味着如果变量值发生变化，样式也会更新。

<script setup lang="ts">
const color = ref("red");
</script>

<template>
  <div class="text">hello</div>
</template>

<style>
.text {
  color: v-bind(color);
}
</style>

状态管理

https://nuxt.com/docs/getting-started/state-management

Nuxt 提供了 useState 组合函数，用于在组件之间创建一个响应式和支持 SSR 的共享状态。

useState 是一个支持 SSR 的 ref 替代品。它的值将在服务器端渲染后（在客户端水合时）保持，并通过一个唯一的键在所有组件之间共享。

pages/index.vue

<script setup lang="ts">
// 定义一个状态并初始化
const counter = useState("counter", () => Math.round(Math.random() * 1000));

// 修改状态
counter.value++;
</script>

<template>
  <div>
    计数器: {{ counter }}
    <button @click="counter++">+</button>
    <button @click="counter--">-</button>
  </div>
</template>

pages/about.vue

<script setup lang="ts">
// 获取一个状态
const counter = useState("counter");
</script>

有两种方法可以指定页面预渲染：

1️⃣ 在 nuxt.config.ts 中配置 routeRules

nuxt.config.ts

export default defineNuxtConfig({
  /** 服务器路由渲染规则 */
  routeRules: {
    "/privacy-policy": { prerender: true },
  },
});

2️⃣ 在页面中配置 defineRouteRules

pages/index.vue

<script setup lang="ts">
defineRouteRules({
  prerender: true,
});
</script>

nuxt.config.ts

export default defineNuxtConfig({
  /** 实验性配置 */
  experimental: {
    inlineRouteRules: true, // 启用后可以在路由组件中使用 defineRouteRules() 配置 prerender
  },
});

部署

package.json

{
  "scripts": {
    "dev": "nuxi dev --dotenv .env.development --host",
    "build": "nuxi build --dotenv .env.production",
    "build:dev": "nuxi build --dotenv .env.development",
    "build:stage": "nuxi build --dotenv .env.stage",
    "prepare": "nuxi prepare",
    "preview": "nuxi preview",
    "generate": "nuxi generate",
    "deploy": "PORT=5000 node .output/server/index.mjs",
    "postinstall": "nuxi prepare",
    "lint": "eslint .",
    "lint-fix": "eslint . --fix"
  }
}

Node 服务器部署

1️⃣ 打包

pnpm run build

打包后将生成 .output 目录，该目录包含所有静态资源文件和服务器文件。其中 /server 是 Node 服务器相关文件，/public 是静态资源文件。

如果配置了静态资源路径，则可以将 public 文件夹中的内容上传到指定 CDN 目录

NUXT_APP_CDN_URL=https://cdn.example.com

2️⃣ 启动服务器

PORT=5000 node .output/server/index.mjs

PM2 部署

ecosystem.config.cjs

module.exports = {
  apps: [
    {
      name: "NuxtAppName",
      port: "5000",
      exec_mode: "cluster",
      instances: "max",
      script: "./.output/server/index.mjs",
    },
  ],
};

1️⃣ 打包

pnpm run build

2️⃣ 启动服务器

pm2 start ecosystem.config.cjs

升级指南

要升级 Nuxt 到最新版本，请使用 nuxi upgrade 命令。

pnpm dlx nuxi upgrade

Get Started

安装

配置

环境覆盖

环境变量

应用程序变量

视图 Views

入口点 app.vue

组件 components

页面 pages

布局 layouts

高级扩展

资源

样式

本地样式表

全局样式表

处理全局样式变量

使用 `v-bind` 绑定动态样式

状态管理

服务器

预渲染

静态资源托管

混合渲染

部署

Node 服务器部署

PM2 部署

升级指南