nuxt-production by secondsky/claude-skills
npx skills add https://github.com/secondsky/claude-skills --skill nuxt-production水合、性能、测试、部署和迁移模式。
1. 数据获取的中断控制
const controller = ref<AbortController>()
const { data } = await useAsyncData(
'users',
() => $fetch('/api/users', { signal: controller.value?.signal })
)
const abortRequest = () => {
controller.value?.abort()
controller.value = new AbortController()
}
2. 异步数据处理器提取
3. 增强的错误处理
1. 增强的块稳定性
2. 延迟水合
<script setup>
const LazyComponent = defineLazyHydrationComponent(() =>
import('./HeavyComponent.vue')
)
</script>
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 变更 | v3 | v4 |
|---|---|---|
| 源码目录 | 根目录 | app/ |
| 数据响应性 | 深层 | 浅层(默认) |
| 默认值 | null | undefined |
| 路由中间件 | 客户端 | 服务器 |
| 应用清单 | 可选 | 默认 |
在以下情况加载 references/hydration.md:
在以下情况加载 references/performance.md:
在以下情况加载 references/testing-vitest.md:
在以下情况加载 references/deployment-cloudflare.md:
| 原因 | 示例 | 修复方法 |
|---|---|---|
| 非确定性值 | Math.random() | 使用 useState |
| 服务器上的浏览器 API | window.innerWidth | 使用 onMounted |
| 服务器上的日期/时间 | new Date() | 使用 useState 或 ClientOnly |
| 第三方脚本 | 分析工具 | 使用 ClientOnly |
非确定性值:
<!-- 错误 -->
<script setup>
const id = Math.random()
</script>
<!-- 正确 -->
<script setup>
const id = useState('random-id', () => Math.random())
</script>
浏览器 API:
<!-- 错误 -->
<script setup>
const width = window.innerWidth // 在服务器上崩溃!
</script>
<!-- 正确 -->
<script setup>
const width = ref(0)
onMounted(() => {
width.value = window.innerWidth
})
</script>
ClientOnly 组件:
<template>
<!-- 包装仅客户端内容 -->
<ClientOnly>
<MyMapComponent />
<template #fallback>
<div class="skeleton">加载地图中...</div>
</template>
</ClientOnly>
</template>
条件渲染:
<script setup>
const showWidget = ref(false)
onMounted(() => {
// 仅在水合后显示
showWidget.value = true
})
</script>
<template>
<AnalyticsWidget v-if="showWidget" />
</template>
<script setup>
// 懒加载重型组件
const HeavyChart = defineAsyncComponent(() =>
import('~/components/HeavyChart.vue')
)
// 带有加载/错误状态
const HeavyChart = defineAsyncComponent({
loader: () => import('~/components/HeavyChart.vue'),
loadingComponent: LoadingSpinner,
errorComponent: ErrorFallback,
delay: 200,
timeout: 10000
})
</script>
<template>
<Suspense>
<HeavyChart :data="chartData" />
<template #fallback>
<LoadingSpinner />
</template>
</Suspense>
</template>
<script setup>
// 在视口中可见时水合
const LazyComponent = defineLazyHydrationComponent(
() => import('./HeavyComponent.vue'),
{ hydrate: 'visible' }
)
// 用户交互时水合
const InteractiveComponent = defineLazyHydrationComponent(
() => import('./InteractiveComponent.vue'),
{ hydrate: 'interaction' }
)
// 浏览器空闲时水合
const IdleComponent = defineLazyHydrationComponent(
() => import('./IdleComponent.vue'),
{ hydrate: 'idle' }
)
</script>
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
// 静态页面(构建时预渲染)
'/': { prerender: true },
'/about': { prerender: true },
// SWR 缓存(1小时)
'/blog/**': { swr: 3600 },
// ISR(每小时重新生成)
'/products/**': { isr: 3600 },
// SPA 模式(无 SSR)
'/dashboard/**': { ssr: false },
// 静态页面带 CDN 缓存
'/static/**': {
headers: { 'Cache-Control': 'public, max-age=31536000' }
}
}
})
<template>
<!-- 使用 NuxtImg 自动优化 -->
<NuxtImg
src="/images/hero.jpg"
alt="Hero image"
width="800"
height="400"
loading="lazy"
placeholder
format="webp"
/>
<!-- 响应式图片 -->
<NuxtPicture
src="/images/product.jpg"
alt="Product"
sizes="sm:100vw md:50vw lg:400px"
:modifiers="{ quality: 80 }"
/>
</template>
bun add -d @nuxt/test-utils vitest @vue/test-utils happy-dom
// vitest.config.ts
import { defineVitestConfig } from '@nuxt/test-utils/config'
export default defineVitestConfig({
test: {
environment: 'nuxt',
environmentOptions: {
nuxt: {
domEnvironment: 'happy-dom'
}
}
}
})
// tests/components/UserCard.test.ts
import { describe, it, expect } from 'vitest'
import { mountSuspended } from '@nuxt/test-utils/runtime'
import UserCard from '~/components/UserCard.vue'
describe('UserCard', () => {
it('渲染用户名', async () => {
const wrapper = await mountSuspended(UserCard, {
props: {
user: { id: 1, name: 'John Doe', email: 'john@example.com' }
}
})
expect(wrapper.text()).toContain('John Doe')
expect(wrapper.text()).toContain('john@example.com')
})
it('触发删除事件', async () => {
const wrapper = await mountSuspended(UserCard, {
props: { user: { id: 1, name: 'John' } }
})
await wrapper.find('[data-test="delete-btn"]').trigger('click')
expect(wrapper.emitted('delete')).toHaveLength(1)
expect(wrapper.emitted('delete')[0]).toEqual([1])
})
})
// tests/components/Dashboard.test.ts
import { describe, it, expect, vi } from 'vitest'
import { mountSuspended, mockNuxtImport } from '@nuxt/test-utils/runtime'
import Dashboard from '~/pages/dashboard.vue'
// 模拟 useFetch
mockNuxtImport('useFetch', () => {
return () => ({
data: ref({ users: [{ id: 1, name: 'John' }] }),
pending: ref(false),
error: ref(null)
})
})
describe('Dashboard', () => {
it('显示来自 API 的用户', async () => {
const wrapper = await mountSuspended(Dashboard)
expect(wrapper.text()).toContain('John')
})
})
// tests/api/users.test.ts
import { describe, it, expect } from 'vitest'
import { $fetch, setup } from '@nuxt/test-utils/e2e'
describe('API: /api/users', async () => {
await setup({ server: true })
it('返回用户列表', async () => {
const users = await $fetch('/api/users')
expect(users).toHaveProperty('users')
expect(Array.isArray(users.users)).toBe(true)
})
it('创建新用户', async () => {
const result = await $fetch('/api/users', {
method: 'POST',
body: { name: 'Jane', email: 'jane@example.com' }
})
expect(result.user.name).toBe('Jane')
})
})
# 构建和部署
bun run build
bunx wrangler pages deploy .output/public
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'cloudflare-pages'
}
})
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'cloudflare-module'
}
})
# wrangler.toml
name = "my-nuxt-app"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxx-xxx-xxx"
[[kv_namespaces]]
binding = "KV"
id = "xxx-xxx-xxx"
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'vercel'
}
})
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'netlify'
}
})
bun add @nuxthub/core
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxthub/core'],
hub: {
database: true, // D1
kv: true, // KV
blob: true, // R2
cache: true // Cache API
}
})
// 在服务器路由中使用
export default defineEventHandler(async (event) => {
const db = hubDatabase()
const kv = hubKV()
const blob = hubBlob()
// 像常规 Cloudflare 绑定一样使用
const users = await db.prepare('SELECT * FROM users').all()
})
# .env(开发环境)
API_SECRET=dev-secret
DATABASE_URL=http://localhost:8787
# 生产环境(Cloudflare)
wrangler secret put API_SECRET
wrangler secret put DATABASE_URL
# 生产环境(Vercel/Netlify)
# 在控制台或 CLI 中设置
{
"devDependencies": {
"nuxt": "^4.0.0"
}
}
// nuxt.config.ts
export default defineNuxtConfig({
future: {
compatibilityVersion: 4
}
})
# 创建 app 目录
mkdir app
# 移动文件
mv components app/
mv composables app/
mv pages app/
mv layouts app/
mv middleware app/
mv plugins app/
mv assets app/
mv app.vue app/
mv error.vue app/
// 如果修改 data.value 属性:
const { data } = await useFetch('/api/user', {
deep: true // 启用深层响应性
})
// 或者替换整个值
data.value = { ...data.value, name: 'New Name' }
// v3: data.value 是 null
// v4: data.value 是 undefined
// 更新 null 检查
if (data.value === null) // v3
if (!data.value) // v4(两者都适用)
// 错误
const width = window.innerWidth
// 正确
if (import.meta.client) {
const width = window.innerWidth
}
// 或者使用 onMounted
onMounted(() => {
const width = window.innerWidth
})
// 错误 - 服务器与客户端不同
const id = Math.random()
const time = Date.now()
// 正确 - 使用 useState 保持一致性
const id = useState('id', () => Math.random())
const time = useState('time', () => Date.now())
<!-- 错误 -->
<AsyncComponent />
<!-- 正确 -->
<Suspense>
<AsyncComponent />
<template #fallback>
<LoadingSpinner />
</template>
</Suspense>
水合不匹配:
window、document、localStorage 的使用ClientOnly 包装或使用 onMountedMath.random()、Date.now()、crypto.randomUUID() 的使用构建错误:
rm -rf .nuxt .output node_modules/.vite && bun install
部署失败:
nitro.preset 是否与目标匹配测试失败:
@nuxt/test-utilsenvironment: 'nuxt'mountSuspended版本 : 4.0.0 | 最后更新 : 2025-12-28 | 许可证 : MIT
每周安装量
90
代码仓库
GitHub 星标数
93
首次出现
2026年1月25日
安全审计
安装于
claude-code82
codex73
gemini-cli72
opencode71
github-copilot69
cursor69
Hydration, performance, testing, deployment, and migration patterns.
1. Abort Control for Data Fetching
const controller = ref<AbortController>()
const { data } = await useAsyncData(
'users',
() => $fetch('/api/users', { signal: controller.value?.signal })
)
const abortRequest = () => {
controller.value?.abort()
controller.value = new AbortController()
}
2. Async Data Handler Extraction
3. Enhanced Error Handling
1. Enhanced Chunk Stability
2. Lazy Hydration
<script setup>
const LazyComponent = defineLazyHydrationComponent(() =>
import('./HeavyComponent.vue')
)
</script>
| Change | v3 | v4 |
|---|---|---|
| Source directory | Root | app/ |
| Data reactivity | Deep | Shallow (default) |
| Default values | null | undefined |
| Route middleware | Client | Server |
| App manifest | Opt-in | Default |
Loadreferences/hydration.md when:
Loadreferences/performance.md when:
Loadreferences/testing-vitest.md when:
Loadreferences/deployment-cloudflare.md when:
| Cause | Example | Fix |
|---|---|---|
| Non-deterministic values | Math.random() | Use useState |
| Browser APIs on server | window.innerWidth | Use onMounted |
| Date/time on server | new Date() | Use useState or ClientOnly |
Non-deterministic Values:
<!-- WRONG -->
<script setup>
const id = Math.random()
</script>
<!-- CORRECT -->
<script setup>
const id = useState('random-id', () => Math.random())
</script>
Browser APIs:
<!-- WRONG -->
<script setup>
const width = window.innerWidth // Crashes on server!
</script>
<!-- CORRECT -->
<script setup>
const width = ref(0)
onMounted(() => {
width.value = window.innerWidth
})
</script>
ClientOnly Component:
<template>
<!-- Wrap client-only content -->
<ClientOnly>
<MyMapComponent />
<template #fallback>
<div class="skeleton">Loading map...</div>
</template>
</ClientOnly>
</template>
Conditional Rendering:
<script setup>
const showWidget = ref(false)
onMounted(() => {
// Only show after hydration
showWidget.value = true
})
</script>
<template>
<AnalyticsWidget v-if="showWidget" />
</template>
<script setup>
// Lazy load heavy components
const HeavyChart = defineAsyncComponent(() =>
import('~/components/HeavyChart.vue')
)
// With loading/error states
const HeavyChart = defineAsyncComponent({
loader: () => import('~/components/HeavyChart.vue'),
loadingComponent: LoadingSpinner,
errorComponent: ErrorFallback,
delay: 200,
timeout: 10000
})
</script>
<template>
<Suspense>
<HeavyChart :data="chartData" />
<template #fallback>
<LoadingSpinner />
</template>
</Suspense>
</template>
<script setup>
// Hydrate when visible in viewport
const LazyComponent = defineLazyHydrationComponent(
() => import('./HeavyComponent.vue'),
{ hydrate: 'visible' }
)
// Hydrate on user interaction
const InteractiveComponent = defineLazyHydrationComponent(
() => import('./InteractiveComponent.vue'),
{ hydrate: 'interaction' }
)
// Hydrate when browser is idle
const IdleComponent = defineLazyHydrationComponent(
() => import('./IdleComponent.vue'),
{ hydrate: 'idle' }
)
</script>
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
// Static pages (prerendered at build)
'/': { prerender: true },
'/about': { prerender: true },
// SWR caching (1 hour)
'/blog/**': { swr: 3600 },
// ISR (regenerate every hour)
'/products/**': { isr: 3600 },
// SPA mode (no SSR)
'/dashboard/**': { ssr: false },
// Static with CDN caching
'/static/**': {
headers: { 'Cache-Control': 'public, max-age=31536000' }
}
}
})
<template>
<!-- Automatic optimization with NuxtImg -->
<NuxtImg
src="/images/hero.jpg"
alt="Hero image"
width="800"
height="400"
loading="lazy"
placeholder
format="webp"
/>
<!-- Responsive images -->
<NuxtPicture
src="/images/product.jpg"
alt="Product"
sizes="sm:100vw md:50vw lg:400px"
:modifiers="{ quality: 80 }"
/>
</template>
bun add -d @nuxt/test-utils vitest @vue/test-utils happy-dom
// vitest.config.ts
import { defineVitestConfig } from '@nuxt/test-utils/config'
export default defineVitestConfig({
test: {
environment: 'nuxt',
environmentOptions: {
nuxt: {
domEnvironment: 'happy-dom'
}
}
}
})
// tests/components/UserCard.test.ts
import { describe, it, expect } from 'vitest'
import { mountSuspended } from '@nuxt/test-utils/runtime'
import UserCard from '~/components/UserCard.vue'
describe('UserCard', () => {
it('renders user name', async () => {
const wrapper = await mountSuspended(UserCard, {
props: {
user: { id: 1, name: 'John Doe', email: 'john@example.com' }
}
})
expect(wrapper.text()).toContain('John Doe')
expect(wrapper.text()).toContain('john@example.com')
})
it('emits delete event', async () => {
const wrapper = await mountSuspended(UserCard, {
props: { user: { id: 1, name: 'John' } }
})
await wrapper.find('[data-test="delete-btn"]').trigger('click')
expect(wrapper.emitted('delete')).toHaveLength(1)
expect(wrapper.emitted('delete')[0]).toEqual([1])
})
})
// tests/components/Dashboard.test.ts
import { describe, it, expect, vi } from 'vitest'
import { mountSuspended, mockNuxtImport } from '@nuxt/test-utils/runtime'
import Dashboard from '~/pages/dashboard.vue'
// Mock useFetch
mockNuxtImport('useFetch', () => {
return () => ({
data: ref({ users: [{ id: 1, name: 'John' }] }),
pending: ref(false),
error: ref(null)
})
})
describe('Dashboard', () => {
it('displays users from API', async () => {
const wrapper = await mountSuspended(Dashboard)
expect(wrapper.text()).toContain('John')
})
})
// tests/api/users.test.ts
import { describe, it, expect } from 'vitest'
import { $fetch, setup } from '@nuxt/test-utils/e2e'
describe('API: /api/users', async () => {
await setup({ server: true })
it('returns users list', async () => {
const users = await $fetch('/api/users')
expect(users).toHaveProperty('users')
expect(Array.isArray(users.users)).toBe(true)
})
it('creates a new user', async () => {
const result = await $fetch('/api/users', {
method: 'POST',
body: { name: 'Jane', email: 'jane@example.com' }
})
expect(result.user.name).toBe('Jane')
})
})
# Build and deploy
bun run build
bunx wrangler pages deploy .output/public
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'cloudflare-pages'
}
})
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'cloudflare-module'
}
})
# wrangler.toml
name = "my-nuxt-app"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxx-xxx-xxx"
[[kv_namespaces]]
binding = "KV"
id = "xxx-xxx-xxx"
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'vercel'
}
})
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
preset: 'netlify'
}
})
bun add @nuxthub/core
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxthub/core'],
hub: {
database: true, // D1
kv: true, // KV
blob: true, // R2
cache: true // Cache API
}
})
// Usage in server routes
export default defineEventHandler(async (event) => {
const db = hubDatabase()
const kv = hubKV()
const blob = hubBlob()
// Use like regular Cloudflare bindings
const users = await db.prepare('SELECT * FROM users').all()
})
# .env (development)
API_SECRET=dev-secret
DATABASE_URL=http://localhost:8787
# Production (Cloudflare)
wrangler secret put API_SECRET
wrangler secret put DATABASE_URL
# Production (Vercel/Netlify)
# Set in dashboard or CLI
{
"devDependencies": {
"nuxt": "^4.0.0"
}
}
// nuxt.config.ts
export default defineNuxtConfig({
future: {
compatibilityVersion: 4
}
})
# Create app directory
mkdir app
# Move files
mv components app/
mv composables app/
mv pages app/
mv layouts app/
mv middleware app/
mv plugins app/
mv assets app/
mv app.vue app/
mv error.vue app/
// If mutating data.value properties:
const { data } = await useFetch('/api/user', {
deep: true // Enable deep reactivity
})
// Or replace entire value
data.value = { ...data.value, name: 'New Name' }
// v3: data.value is null
// v4: data.value is undefined
// Update null checks
if (data.value === null) // v3
if (!data.value) // v4 (works for both)
// WRONG
const width = window.innerWidth
// CORRECT
if (import.meta.client) {
const width = window.innerWidth
}
// Or use onMounted
onMounted(() => {
const width = window.innerWidth
})
// WRONG - Different on server vs client
const id = Math.random()
const time = Date.now()
// CORRECT - Use useState for consistency
const id = useState('id', () => Math.random())
const time = useState('time', () => Date.now())
<!-- WRONG -->
<AsyncComponent />
<!-- CORRECT -->
<Suspense>
<AsyncComponent />
<template #fallback>
<LoadingSpinner />
</template>
</Suspense>
Hydration Mismatch:
window, document, localStorage usageClientOnly or use onMountedMath.random(), Date.now(), crypto.randomUUID()Build Errors:
rm -rf .nuxt .output node_modules/.vite && bun install
Deployment Fails:
nitro.preset matches targetTests Failing:
@nuxt/test-utils is installedenvironment: 'nuxt'mountSuspended for async componentsVersion : 4.0.0 | Last Updated : 2025-12-28 | License : MIT
Weekly Installs
90
Repository
GitHub Stars
93
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykWarn
Installed on
claude-code82
codex73
gemini-cli72
opencode71
github-copilot69
cursor69
Swift Actor 线程安全持久化:构建离线优先应用的编译器强制安全数据层
1,700 周安装
二进制初步分析指南:使用ReVa工具快速识别恶意软件与逆向工程
69 周安装
PrivateInvestigator 道德人员查找工具 | 公开数据调查、反向搜索与背景研究
69 周安装
TorchTitan:PyTorch原生分布式大语言模型预训练平台,支持4D并行与H100 GPU加速
69 周安装
screenshot 截图技能:跨平台桌面截图工具,支持macOS/Linux权限管理与多模式捕获
69 周安装
tmux进程管理最佳实践:交互式Shell初始化、会话命名与生命周期管理
69 周安装
Git Rebase Sync:安全同步分支的Git变基工具,解决冲突与备份
69 周安装
| Third-party scripts | Analytics | Use ClientOnly |