企业官网建设流程全解析

基于 Nuxt 4 全栈模板搭建 Vue 应用的实战指南（ag-kit App Builder 模板解析）

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit

本篇指南以 ag-kit 仓库中 App Builder 技能的 nuxt-app 模板 为核心，系统讲解如何从零搭建一套 Nuxt 4 全栈应用：涵盖技术选型、app/目录结构、Pinia 状态管理、Tailwind CSS v4 与 Prisma 集成，以及 SSR 场景下的数据请求与类型安全最佳实践。读完你将能够依据该模板独立完成一个 Vue 3 + Nuxt 4 + Pinia + Prisma 项目的初始化与基础架构搭建。

模板定位：Nuxt 4 全栈应用的标准起点

在 ag-kit 的 App Builder 技能体系中，模板目录 共收录 13 套不同技术栈的项目脚手架模板，而nuxt-app是其中面向Vue 全栈应用的专用模板。根据 SKILL.md 的模板索引表，它的适用场景被明确标注为 "Vue full-stack app"——即当用户请求构建基于 Vue 生态的全栈应用时，App Builder 会选择读取 nuxt-app/TEMPLATE.md 作为搭建依据。

模板的选择遵循 project-detection.md 中的关键词矩阵与冲突消解规则：先对用户请求做分词与关键词提取，再判定项目类型；当平台（如mobile、desktop、cli）与业务领域（如e-commerce、crm）冲突时，平台优先。需要说明的是，nuxt-app模板本身聚焦于 Vue 技术栈，若用户请求中出现vue、nuxt等 Vue 生态关键词或对 Vue 全栈形态有明确诉求，该模板即为默认选择。

模板头部声明了其核心能力定位：

name: nuxt-app description: Nuxt 4 full-stack template. Vue 3, Pinia, Tailwind v4, Prisma.

这句 frontmatter 浓缩了整套模板的技术骨架：Nuxt 4 框架 + Vue 3 视图引擎 + Pinia 状态管理 + Tailwind CSS v4 样式体系 + Prisma ORM 数据层，以下逐一展开。

技术栈全景：2026 年 Vue 全栈的组件选型

模板以表格形式给出了完整的选型清单，这是整套架构的"配方"，任何一项都直接影响后续目录结构与代码组织方式：

几个值得注意的选型细节：

• Nuxt v4 的app/srcDir 结构是区别于 Nuxt 3 的最大变化，模板后续的目录结构正是围绕这一约定展开；
• Tailwind v4 采用 Vite 插件接入，而非传统的@nuxtjs/tailwindcss模块（详见下文 Setup 第 3 步的明确提示）；
• Pinia v3 采用 setup store 语法，即以defineStore+ 组合式 API 书写 store，替代 Options store；
• Zod 承担前后端统一的校验职责，与shared/目录配合实现"一次定义、两端复用"。

从模板编写惯例看（对比 nextjs-fullstack 模板 中同样注明 "2026 Edition" 与 "Pin to the current stable when scaffolding"），版本号反映的是 2026 年 5 月已验证的稳定主线，实际脚手架搭建时应以当时的最新稳定版本为准，模板给出的版本线用于锁定选型方向而非精确锁死。

目录结构：Nuxt 4 的 app/ srcDir 布局

Nuxt 4 将默认源码目录srcDir指向app/，从而把客户端代码与server/目录、根级配置文件彻底分离。模板给出的标准结构如下：

project-name/ ├── app/ # 应用源码（Nuxt 4 srcDir） │ ├── assets/css/ │ │ └── main.css # Tailwind v4 导入 │ ├── components/ # 自动导入的组件 │ ├── composables/ # 自动导入的逻辑 │ ├── layouts/ │ ├── middleware/ │ ├── pages/ # 基于文件的路由 │ ├── plugins/ │ ├── stores/ # Pinia stores │ ├── app.vue # 根组件 │ └── app.config.ts # 响应式运行时配置 ├── server/ # Nitro 服务引擎 │ ├── api/ # API 路由（如 /api/users） │ ├── routes/ # 服务端路由 │ └── utils/ # 仅服务端使用的助手（如 Prisma client） ├── shared/ # 同构代码（类型、Zod schemas） ├── prisma/ │ └── schema.prisma ├── public/ ├── nuxt.config.ts └── package.json

这套结构与 scaffolding.md 中强调的工程化原则一脉相承——"服务端/客户端分离"是 ag-kit App Builder 技能在所有模板中反复强化的核心原则（Next.js 模板同样要求将服务端逻辑隔离在lib/层，防止被客户端意外引入）。对 Nuxt 4 而言，这种分离通过三个关键目录实现：

• app/：一切客户端代码的根。components/、composables/目录中的文件会被 Nuxt自动导入，无需手动import；pages/采用基于文件的路由约定，新增一个.vue文件即新增一条路由；
• server/：Nitro 服务引擎的代码根。api/下每个文件对应一个 API 端点（如server/api/users.get.ts对应GET /api/users），routes/用于非 API 服务端路由，utils/存放仅服务端可见的助手——模板明确要求Prisma client 实例化在这里，以保证其永不进入客户端打包产物；
• shared/：同构代码层，Vue 应用与 Nitro 服务端均可导入。类型定义与 Zod 校验 schema 放在此处，实现前后端单一数据源。

关键概念：2026 版 Nuxt 的核心机制

模板用一张概念表概括了使用 Nuxt 4 必须掌握的五个机制：

其中Vapor Mode是 Nuxt 4 引入的前瞻性特性：它通过移除虚拟 DOM 层来降低运行时开销，以 "per component"（按组件粒度）的方式选择启用。模板明确提示该特性在 2026 年尚未 GA（正式发布），<script setup vapor>的启用方式也是以"将来正式发布后"为条件表述的，因此生产项目现阶段应将其视为观察项而非依赖项——这体现了模板对实验特性"谨慎引入、标注前提"的务实态度。

环境变量：三个必配项的职责划分

模板定义了全栈应用运行所需的三类核心环境变量：

这三个变量覆盖了应用的三条关键链路：

• DATABASE_URL是数据层的入口，由server/utils/中的 Prisma client 读取，指向 PostgreSQL 实例；
• NUXT_PUBLIC_APP_URL带NUXT_PUBLIC_前缀，意味着它会被 Nuxt 自动暴露到客户端 bundle，供浏览器端访问（如生成规范链接、分享 URL），适用于"客户端也需要知道站点地址"的场景；
• NUXT_SESSION_PASSWORD用于对 Session 数据做加密签名，属于服务端机密，不应以NUXT_PUBLIC_前缀暴露。

在.env文件中配置时，建议同步维护一份.env.example作为环境模板提交到仓库，供其他开发者按需填充（这也是 scaffolding.md 对工程模板的一贯要求）。

搭建步骤：从空目录到可运行项目

模板给出了五步初始化流程，下面结合源码上下文逐条展开，补充关键注释与可选参数，使其可直接复制运行。

第 1 步：初始化项目

npx nuxi@latest init my-app

使用 Nuxt 官方 CLI（nuxi）创建项目骨架，my-app替换为你的项目名。初始化完成后进入项目目录继续后续步骤。

第 2 步：安装核心依赖

npm install @pinia/nuxt @prisma/client zod npm install -D prisma

• @pinia/nuxt：Pinia 的 Nuxt 模块，安装后即可在stores/目录中使用defineStore定义全局状态；
• @prisma/client+prisma（开发依赖）：Prisma ORM 的运行时与 CLI，prisma用于 schema 管理与迁移；
• zod：Schema 校验库，与shared/目录配合做前后端统一的输入校验。

第 3 步：接入 Tailwind v4（Vite 插件方式）

模板特别强调：使用官方 Vite 插件@tailwindcss/vite，而不是旧的@nuxtjs/tailwindcss模块。这是 Tailwind v4 升级后的关键差异。

npm install tailwindcss @tailwindcss/vite

随后在nuxt.config.ts中注册插件并声明全局样式入口：

import tailwindcss from '@tailwindcss/vite' export default defineNuxtConfig({ vite: { plugins: [tailwindcss()] }, css: ['~/assets/css/main.css'] })

其中vite.plugins将 Tailwind 的 Vite 插件注入构建管线，css数组声明全局样式文件路径（~是 Nuxt 对app/目录的别名，等价于 srcDir）。

第 4 步：配置 CSS 主题

在app/assets/css/main.css中导入 Tailwind 并定义主题令牌：

@import "tailwindcss"; @theme { --color-primary: oklch(0.6 0.15 150); }

这是 Tailwind v4 的 "CSS-first" 配置方式：主题定义直接写在 CSS 里，通过@theme指令声明设计令牌（design tokens），例如这里用oklch()颜色函数定义了一个主色--color-primary，之后即可在类名中使用bg-primary、text-primary等工具类。整个流程不需要tailwind.config.js文件。对比 nextjs-fullstack 模板 的 globals.css 配置（同样使用@import "tailwindcss"+@theme），可以看到 "CSS-first 配置、零 config 文件" 已成为 ag-kit 各模板对 Tailwind v4 的统一处理方式，且该模板还额外示范了在@theme中自定义字体变量（--font-sans）的做法，可按需借鉴。

第 5 步：启动开发服务器

npm run dev

Nuxt 会启动基于 Vite 的本地开发服务器（默认http://localhost:3000），支持热更新。此时访问页面即可验证整套脚手架（Vue 渲染、Tailwind 样式、Nitro 服务端）是否协同工作。

最佳实践：SSR 应用的五条工程准则

模板以清单形式给出了 Nuxt 4 全栈应用的核心工程准则，这些条目直接映射到上面介绍的目录结构与技术选型，是"目录为什么这样分、库为什么这样选"的最终答案：

• 数据请求：优先使用useFetch/useAsyncData进行 SSR 友好的数据请求；仅当明确需要纯客户端场景时才使用server: false选项。这样页面首屏由服务端直接渲染出数据，兼顾 SEO 与首屏性能，避免客户端二次请求造成的闪烁与瀑布流请求；
• 状态管理：全局状态用 Pinia（defineStore）管理；简单的、仅需 SSR 共享的状态用 Nuxt 内置的useState。useState是 Nuxt 提供的 SSR 安全状态原语，会在服务端与客户端之间保持同一份共享状态，适合无需复杂派生逻辑的轻量场景；
• 输入校验：将 Zod schema 定义在shared/目录，客户端表单与 Nitro API 路由复用同一份 schema。这保证了同一字段的校验规则在浏览器端（即时反馈）与服务端（权威校验）完全一致，杜绝"前端校验过了、后端报错"的规则漂移；
• 类型安全：API 路由的类型由$fetch自动推断。Nuxt 的$fetch基于 Nitro 路由自动生成类型，前后端共享类型定义后，调用$fetch('/api/users')时返回值类型自动对齐服务端路由的实际返回类型，接口变更会在编译期暴露；
• 服务端专属：Prisma client 只在server/utils/中实例化，确保数据库访问代码永不泄漏到客户端 bundle。这一点与目录结构一节中server/utils/的定位完全对应，是防止数据库连接串与查询逻辑暴露在浏览器端的安全底线。

模板在 App Builder 工作流中的位置

回到 ag-kit 的整体视角：nuxt-app模板不是孤立的参考文档，而是 App Builder 技能编排链路中的一环。从 agent-coordination.md 的流水线可见，当 App Builder 完成项目类型判定并选定模板后，会依次经过 Project Planner（产出{task-slug}.md计划文件）→ 计划校验关卡 → 数据库架构师 / 后端专家 / 前端专家（UI 项目还需先产出DESIGN.md）→ 安全审计 / 测试 → DevOps 预览部署等阶段。模板与这些流程的关系是：

• 模板管"骨架"：目录结构、技术选型、依赖清单、初始化命令，由 templates/SKILL.md 的"只读取与项目类型匹配的那一个模板"规则约束，避免跨技术栈的配置污染；
• 流水线管"血肉"：具体页面的实现、API 的编写、数据库 schema 的设计由各专业 Agent 在模板给定的结构内完成，例如前端专家在app/components/、app/pages/中落地 UI，后端专家在server/api/中实现端点，数据库架构师维护prisma/schema.prisma与迁移。

因此，理解这份模板，本质上是理解了 ag-kit 在构建 Vue 全栈应用时对目录约定、依赖选择与代码组织方式的全部默认决策；在此基础上，你可以完全照搬模板完成脚手架搭建，也可以将模板作为基线，按业务需要替换其中的某一块（例如将数据库从 PostgreSQL 换为其他 Prisma 支持的方言，或在shared/中扩充业务 schema），其余结构依然成立。

小结

本文围绕 ag-kit App Builder 的 nuxt-app 模板 展开，完整覆盖了它的技术栈选型、app/srcDir 目录结构、Nitro 服务端引擎、Tailwind v4 的 CSS-first 主题配置、三组核心环境变量、五步初始化流程，以及 SSR 数据请求、Pinia 状态管理、Zod 前后端共用校验等最佳实践。同时结合 SKILL.md、templates/SKILL.md、project-detection.md、agent-coordination.md 与 scaffolding.md 等仓库内文档，说明了模板在 App Builder 技能体系中的定位与调用方式。若要继续深入，可前往仓库.agents/skills/app-builder/templates/目录横向对比其他 12 套模板，观察不同技术栈之间共享的工程原则（服务端/客户端分离、单一数据源、严格模式 TypeScript），这有助于在团队内形成统一、可复制的项目初始化方法论。

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit