如何用 ECC 开发 Nuxt 4 应用？

如何用 ECC 开发 Nuxt 4 应用【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC如果你正在用 agent harness如 Claude Code开发 Nuxt 4 应用ECC 提供了一条可直接落地的协作路径它的nuxt4-patternsskill 定义了数据获取、渲染策略与懒加载的取舍标准rules/nuxt/下的五个规则文件则按文件路径自动约束代码风格、安全与测试写法并配有 lint 与 typecheck 的自动校验链。装好 ECC 后你在 Nuxt 4 项目中的页面数据、路由规则和验证命令都按这套模式执行而不是靠个人习惯。前提Node.js 18 或更新版本、Git、Claude Code 2.1 或更新版本在PATH上项目为 Nuxt 4 应用默认srcDir为app/。安装 ECC 并确认 Nuxt 规则就位在终端执行官方引导安装npx ecc-universal setup如果 npm 报版本或缓存错误先用npm view ecc-universal version确认 registry 版本再重试。该命令会安全地安装、更新或迁移一个eccecc插件作用域并记录你选择的 hook profile。另一条等效路径是在 Claude Code 内部执行原生插件命令/plugin marketplace add https://github.com/affaan-m/ECC /plugin install eccecc两条路径安装的是同一个eccecc插件只选一条不要叠加第二次手动安装。安装完成后与 Nuxt 4 开发相关的资料在仓库中对应nuxt4-patterns skill数据获取、hydration 安全、route rules、懒加载的模式与评审清单rules/nuxt/patterns.md、coding-style.md、security.md、testing.md、hooks.md分别覆盖模式、风格、安全、测试与自动校验。每个规则文件的 frontmatter 中声明了paths匹配范围例如**/nuxt.config.*、**/pages/**、**/server/**/*.ts、**/middleware/**。你在这些路径下编辑文件时对应规则生效。先确认目录布局与配置文件分工写代码前核对 目录约定默认srcDir是app/框架文件在app/pages/、app/layouts/、app/middleware/、app/plugins/、app/app.config.tsnuxt.config.ts与server/留在项目根目录。有些项目把srcDir重写为src/例如 Feature-Sliced Design并重新映射dir.pages、dir.layouts和/~别名。在假定任何路径前先检查nuxt.config.ts。app/composables/与server/utils/中的 composable 自动导入。不要手动 import Nuxt composablesuseFetch、useState、navigateTo也不要手动引入defineStore/storeToRefs。不要单独添加vue-router依赖Nuxt 已捆绑 v5也不要手动挂载createApp/createPinia/createRouter。definePageMeta是编译期宏只接受静态值不要放响应式数据或带副作用的调用类型增强用declare module #app扩展PageMeta。三个配置文件职责不同不要混用文件用途nuxt.config.ts仅构建期routeRules、modules、nitro、ssr标志不响应式runtimeConfignuxt.config 内每环境运行时值可用NUXT_*环境变量覆盖根键仅服务端可见public键客户端可见app/app.config.ts构建期固定的公共响应式配置主题 token、feature flags无环境变量覆盖永远不放密钥Head 与 metaapp.head只接受静态值响应式 meta 走组件 setup 里的useHead/useSeoMeta。按渲染时机选择数据获取方式数据获取选型是 Nuxt 4 开发中的重点判断按渲染时机选而不是按习惯useFetch(url)SSR 安全的默认选择。首屏/首次渲染的 URL 数据用它服务端结果通过 payload 转发hydration 时不会二次请求。useAsyncData(key, fn)SSR 安全适合自定义异步逻辑SDK / GraphQL / 组合调用。显式 key 让结果在组件间共享给一个稳定的 key如基于路由参数生成便于缓存复用和可预测的刷新。$fetch只用于客户端交互表单提交、按钮点击、POST/PUT/DELETE。它不是 SSR 安全的首屏数据方案用于首屏会造成 double-fetch。skill 中的示例文档示例接口路径按你的项目替换const route useRoute() const { data: article, status, error, refresh } await useAsyncData( () article:${route.params.slug}, () $fetch(/api/articles/${route.params.slug}), ) const { data: comments } await useFetch(/api/articles/${route.params.slug}/comments, { lazy: true, server: false, })配套规则useAsyncData()的 handler 保持无副作用因为它可能在 SSR 和 hydration 阶段运行。非关键数据用lazy: true、useLazyFetch()或useLazyAsyncData()让数据不阻塞导航并在 UI 中处理status pending。server: false只用于 SEO 和首屏都不需要的数据。用pick精简 payload注意它只减小序列化体积不会跳过请求本身。用 routeRules 配置渲染与缓存策略在nuxt.config.ts中按路由组配置文档示例export default defineNuxtConfig({ routeRules: { /: { prerender: true }, /products/**: { swr: 3600 }, /blog/**: { isr: true }, /admin/**: { ssr: false }, /api/**: { cache: { maxAge: 60 * 60 } }, }, })各选项含义prerender构建时生成静态 HTMLswr提供缓存内容并在后台重新验证isr在支持平台上增量静态再生成ssr: false客户端渲染路由cache或redirectNitro 层级的响应行为按路由组而非全局选择策略——营销页、商品目录、后台、API 通常需要不同的渲染与缓存方式。保持 SSR 首帧与客户端 hydration 一致hydration 失配是 Nuxt 4 开发中最常见的问题skill 给出的安全规则首次渲染必须确定性不要把Date.now()、Math.random()、浏览器专属 API 或 storage 读取直接放进 SSR 渲染的模板状态。服务端无法产生相同 markup 的逻辑放到onMounted()、import.meta.client、ClientOnly或.client.vue组件后面。使用 Nuxt 的useRoute()composable不是vue-router导出的那个。不要用route.fullPath驱动 SSR 渲染的 markupURL fragment 是客户端专属的会造成 hydration 失配。ssr: false是真正浏览器专属区域的逃生舱不是失配的默认修法。懒加载方面Nuxt 已按路由做代码分割先保持路由边界有意义再做组件级拆分。用Lazy前缀动态导入非关键组件并配合v-if条件渲染让 chunk 在真正需要时才加载template LazyRecommendations v-ifshowRecommendations / LazyProductGallery hydrate-on-visible / /template首屏以下的交互 UI 用 lazy hydration自定义策略用defineLazyHydrationComponent()配 visibility 或 idle 策略。注意 lazy hydration 只作用于单文件组件给已懒 hydration 的组件传入新 props 会立即触发 hydration。站内导航统一用NuxtLinkNuxt 才能预取路由组件与生成的 payload。编写 Nitro 服务端路由与中间件server/api/*.{get,post}.ts按路径 方法自动注册handler 形如defineEventHandler((event) ...)。错误用throw createError({ status, statusText })优先使用 Web-API 风格的status/statusTextstatusCode/statusMessage已弃用。server/middleware/不要返回响应只能修改event.context或设置响应头。路由中间件放在app/middleware/*.ts用defineNuxtRouteMiddleware((to, from) ...)直接使用to/from参数不要在中间件里调useRoute().global后缀表示对所有路由生效返回navigateTo()重定向abortNavigation()中止导航。安全边界rules/nuxt/security.md密钥只放runtimeConfig根键仅服务端。runtimeConfig.public会序列化进每个页面的 payload客户端可见app.config.ts与runtimeConfig.public都不能放密钥。服务端路由不要直接信任readBody/getQuery/getRouterParam改用 h3 的校验读取器readValidatedBody(event, schema)、getValidatedQuery(event, schema)、getValidatedRouterParams(event, schema)均可接受校验函数或 Zod schema失败即抛错。一切写入useState、useFetch/useAsyncData结果或runtimeConfig.public的内容都会序列化进客户端 payload不要把密钥写进去。Nuxt 不会把入站用户的 cookie 自动附加到服务端出站$fetch需要时显式转发useRequestFetch()或useRequestHeaders([cookie])。服务端路由有完整网络出口不要把用户可控输入直接拼进服务端$fetch的 URL 或 host先校验参数并限定目标。用 harness 校验链做验证hooks 文档定义了 Nuxt 工作的自动校验这些 hook 由 harness 执行Typechecknuxi typecheck封装vue-tsc需要vue-tsc与typescript作为 dev 依赖。typecheck 是全项目级别的所以要防抖并包超时文档建议的形态是timeout 60 nuxi typecheck避免挂起的类型检查在快速编辑中累积。Lint用nuxt/eslint模块flat-config、项目感知会生成.nuxt/eslint.config.mjs执行eslint .或eslint --fix。Formatprettier --write或者在nuxt/eslint中启用 stylistic 规则——只选一个格式权威不要同时跑 Prettier 和 ESLint stylistic。建议的 PostToolUse 链对app/**和server/**的每次编辑先执行eslint --fix再执行timeout 60 nuxi typecheck。顺序有讲究lint-fix 会修改文件放在前面带超时的 typecheck 验证结果放在后面。这条链就是开发过程的验证方式每次改动后eslint --fix通过且timeout 60 nuxi typecheck在超时前退出说明当前编辑同时满足静态检查与类型检查。可选为组件与服务端路由加测试如果需要测试覆盖testing 规则给出nuxt/test-utils方案Vitest 优先内置 Playwright 浏览器 E2Enuxt-vitest 与 vitest-environment-nuxt 已被并入其中安装 dev 依赖npm install -D nuxt/test-utils vitest vue/test-utils happy-dom playwright-core配置从nuxt/test-utils/config导入import { defineVitestConfig } from nuxt/test-utils/config export default defineVitestConfig({ test: { environment: nuxt, }, })再把nuxt/test-utils/module加入nuxt.config也可按文件用// vitest-environment nuxt单独开启。运行时 helper 从nuxt/test-utils/runtime导入mountSuspended(component, opts)在 Nuxt 环境中挂载组件支持 async setup 与 plugin 注入、registerEndpoint(path, handler)用于 mock Nitro 端点或替后端打桩、mockNuxtImport(name, factory)mock 自动导入每个 import 每文件一次配合vi.hoisted()。E2E 侧在 describe 块内await setup({ rootDir, server, browser })后可用$fetch(url)取渲染 HTML、fetch(url)取响应对象、createPage(url)起 Playwright 页面。收尾前的评审清单提交前对照 skill 的 Review Checklist 过一遍首次 SSR 渲染与 hydration 后的客户端渲染产生相同 markup页面数据用useFetch或useAsyncData而不是顶层$fetch非关键数据是 lazy 的且有显式的加载 UI路由规则匹配该页面的 SEO 与新鲜度要求重量级交互组件已懒加载或懒 hydration。此外patterns 规则还要求useAsyncData的 payload 走devalueDate/Map/Set/refs 可存活而server/api响应只能JSON.stringify——非 JSON 类型要定义toJSON()共享状态用useState(key, () init)值必须 JSON 可序列化禁止模块作用域export const x ref()并发 SSR 请求间会泄漏同一实例并造成内存泄漏异步的服务端初始化放进callOnce(async () {...})不要作为useAsyncData内部的副作用。按这条路径走完——安装 ECC、确认规则匹配、按模式写数据与路由、跑通 lint typecheck 链、对照清单收尾——一次 Nuxt 4 开发迭代就有了可重复的验证标准。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考