基于 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 全栈的组件选型模板以表格形式给出了完整的选型清单这是整套架构的配方任何一项都直接影响后续目录结构与代码组织方式组件技术版本 / 说明框架Nuxtv4app/srcDir 结构UI 引擎Vuev3稳定版语言TypeScriptv5严格模式 Strict Mode状态管理Piniav3setup store 语法数据库PostgreSQLPrisma ORM样式Tailwind CSSv4tailwindcss/vite插件UI 组件库Nuxt UIv3原生适配 Tailwind v4校验ZodSchema 校验几个值得注意的选型细节Nuxt v4 的app/srcDir 结构是区别于 Nuxt 3 的最大变化模板后续的目录结构正是围绕这一约定展开Tailwind v4 采用 Vite 插件接入而非传统的nuxtjs/tailwindcss模块详见下文 Setup 第 3 步的明确提示Pinia v3 采用 setup store 语法即以defineStore 组合式 API 书写 store替代 Options storeZod 承担前后端统一的校验职责与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自动导入无需手动importpages/采用基于文件的路由约定新增一个.vue文件即新增一条路由server/Nitro 服务引擎的代码根。api/下每个文件对应一个 API 端点如server/api/users.get.ts对应GET /api/usersroutes/用于非 API 服务端路由utils/存放仅服务端可见的助手——模板明确要求Prisma client 实例化在这里以保证其永不进入客户端打包产物shared/同构代码层Vue 应用与 Nitro 服务端均可导入。类型定义与 Zod 校验 schema 放在此处实现前后端单一数据源。关键概念2026 版 Nuxt 的核心机制模板用一张概念表概括了使用 Nuxt 4 必须掌握的五个机制概念说明app/ srcDir客户端代码统一位于app/下与server/和配置干净分离shared/同构代码类型、Zod 校验器Vue 应用与 Nitro 服务端均可使用服务端引擎基于 NitroAPI 路由位于server/api/Prisma client 位于server/utils/Tailwind v4CSS-first 配置主题通过 CSS 中的theme定义不再需要tailwind.config.jsVapor Mode实验性无 VDOM 渲染器2026 年尚未 GA。正式发布后可按组件通过script setup vapor选择启用其中Vapor Mode是 Nuxt 4 引入的前瞻性特性它通过移除虚拟 DOM 层来降低运行时开销以 per component按组件粒度的方式选择启用。模板明确提示该特性在 2026 年尚未 GA正式发布script setup vapor的启用方式也是以将来正式发布后为条件表述的因此生产项目现阶段应将其视为观察项而非依赖项——这体现了模板对实验特性谨慎引入、标注前提的务实态度。环境变量三个必配项的职责划分模板定义了全栈应用运行所需的三类核心环境变量变量用途DATABASE_URLPrisma 连接串PostgreSQLNUXT_PUBLIC_APP_URL站点规范 URLcanonical URLNUXT_SESSION_PASSWORDSession 加密密钥这三个变量覆盖了应用的三条关键链路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 nuxilatest init my-app使用 Nuxt 官方 CLInuxi创建项目骨架my-app替换为你的项目名。初始化完成后进入项目目录继续后续步骤。第 2 步安装核心依赖npm install pinia/nuxt prisma/client zod npm install -D prismapinia/nuxtPinia 的 Nuxt 模块安装后即可在stores/目录中使用defineStore定义全局状态prisma/clientprisma开发依赖Prisma ORM 的运行时与 CLIprisma用于 schema 管理与迁移zodSchema 校验库与shared/目录配合做前后端统一的输入校验。第 3 步接入 Tailwind v4Vite 插件方式模板特别强调使用官方 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 tailwindcsstheme可以看到 CSS-first 配置、零 config 文件 已成为 ag-kit 各模板对 Tailwind v4 的统一处理方式且该模板还额外示范了在theme中自定义字体变量--font-sans的做法可按需借鉴。第 5 步启动开发服务器npm run devNuxt 会启动基于 Vite 的本地开发服务器默认http://localhost:3000支持热更新。此时访问页面即可验证整套脚手架Vue 渲染、Tailwind 样式、Nitro 服务端是否协同工作。最佳实践SSR 应用的五条工程准则模板以清单形式给出了 Nuxt 4 全栈应用的核心工程准则这些条目直接映射到上面介绍的目录结构与技术选型是目录为什么这样分、库为什么这样选的最终答案数据请求优先使用useFetch/useAsyncData进行 SSR 友好的数据请求仅当明确需要纯客户端场景时才使用server: false选项。这样页面首屏由服务端直接渲染出数据兼顾 SEO 与首屏性能避免客户端二次请求造成的闪烁与瀑布流请求状态管理全局状态用 PiniadefineStore管理简单的、仅需 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考