在使用 NuxtHub v0.10.6 构建全栈 Nuxt…

适用于基于 NuxtHub v0.10.6 的 Nuxt 全栈项目，需要 Drizzle 数据库、KV、Blob、Cache 和 Cloudflare/Vercel 等部署配置时。

适用场景

解决思路

1. 构建 Nuxt 服务端模式时使用 `nuxt` skill（server.md）；需要与数据库结合的内容时使用 `nuxt-content` skill。
2. 根据当前任务选择性加载参考文件：手动配置 Cloudflare 的 wrangler.jsonc 时加载 references/wrangler-templates.md；部署到 Vercel、Netlify、Deno、AWS 或配置外部数据库/存储提供商时加载 references/providers.md；不要一次加载全部文件。
3. 安装模块：运行 `npx nuxi module add hub`。
4. 在 nuxt.config.ts 中配置模块：设置 `modules: ['@nuxthub/core']`，并在 `hub` 中设置 `db: 'sqlite'`、`kv: true`、`blob: true`、`cache: true`、`dir: '.data'`、`remote: false`。
5. 使用高级数据库配置：在 `hub.db` 中设置 `dialect`、`driver`、`casing: 'snake_case'`、`migrationsDirs`、`applyMigrationsDuringBuild: true`、`replica.connection.connectionString`。
6. 启用 remote 模式：设置 `hub.remote: true`，在本地开发时连接生产 Cloudflare bindings，而不是本地模拟。
7. 配置数据库读副本：设置 `hub.db.replica.connection.connectionString` 等；查询自动使用副本，写入走主库。
8. 定义数据库 schema：放在 `server/db/schema.ts` 或 `server/db/schema/*.ts`；SQLite 使用 `sqliteTable`、`integer`、`text`，PostgreSQL 使用 `pgTable`、`serial`、`text`、`timestamp`。
9. 使用数据库查询 API：服务端从 `hub:db` 导入 `db` 和 `schema`，也可自动导入；执行 `db.select().from(schema.users)` 或 `db.query.users.findFirst({ where: eq(schema.users.id, 1) })`。
10. 插入数据：使用 `db.insert(schema.users).values({ name: 'John', email: 'john@example.com' }).returning()`。
11. 更新数据：使用 `db.update(schema.users).set({ name: 'Jane' }).where(eq(schema.users.id, 1))`。
12. 删除数据：使用 `db.delete(schema.users).where(eq(schema.users.id, 1))`。
13. 执行迁移命令：使用 `npx nuxt db generate`、`npx nuxt db migrate`、`npx nuxt db sql`、`npx nuxt db drop <TABLE>`、`npx nuxt db drop-all`、`npx nuxt db squash`、`npx nuxt db mark-as-migrated [NAME]`；迁移会在 `npx nuxi dev` 和 `npx nuxi build` 时自动应用，并记录在 `_hub_migrations` 表。
14. 配置数据库提供商：sqlite 本地为 `.data/db/sqlite.db`，生产可用 D1 或 Turso；postgresql 本地为 PGlite，生产可用 postgres-js 或 neon-http；mysql 生产使用 mysql2，并配置对应环境变量。
15. 使用 KV：服务端从 `hub:kv` 导入 `kv`，也可自动导入；调用 `kv.set`、带 `{ ttl: 60 }` 的 `kv.set`、`kv.get`、`kv.has`、`kv.del`、`kv.keys`、`kv.clear`。
16. 遵守 KV 约束：value 最大 25 MiB，key 最大 512 bytes。
17. 配置 KV 提供商：Upstash 使用 `@upstash/redis` 和 `UPSTASH_REDIS_REST_URL`、`UPSTASH_REDIS_REST_TOKEN`；Redis 使用 `ioredis` 和 `REDIS_URL`；Cloudflare KV 使用 wrangler.jsonc 中的 `KV` binding；Deno KV 在 Deno Deploy 自动可用；Vercel 使用 `KV_REST_API_URL`、`KV_REST_API_TOKEN`。
18. 使用 Blob 上传：服务端从 `hub:blob` 导入 `blob`，也可自动导入；调用 `blob.put('path/file.txt', body, { contentType: 'text/plain', access: 'public', addRandomSuffix: true, prefix: 'uploads' })`，返回 `{ pathname, contentType, size, httpEtag, uploadedAt }`。
19. 使用 Blob 下载、列表、服务、删除和元数据：调用 `blob.get`、`blob.list({ prefix: 'uploads/', limit: 10, folded: true })`、`blob.serve(event, 'path/file.txt')`、`blob.del('path/file.txt')`、`blob.del(['file1.txt', 'file2.txt'])`、`blob.head('path/file.txt')`。
20. 使用 Blob 上传处理器：在 server eventHandler 中返回 `blob.handleUpload(event, { formKey: 'files', multiple: true, ensure: { maxSize: '10MB', types: ['image/png', 'image/jpeg'] }, put: { addRandomSuffix: true, prefix: 'images' } })`。
21. 手动上传前校验：调用 `ensureBlob(file, { maxSize: '10MB', types: ['image'] })`。
22. 大文件分片上传：返回 `blob.handleMultipartUpload(event)`，路由为 `/api/files/multipart/[action]/[...pathname]`。
23. Vue 简单上传：使用 `useUpload('/api/upload')`，并调用 `upload(inputElement)`。
24. Vue 分片上传：使用 `useMultipartUpload('/api/files/multipart')`，调用 `mpu(file)` 获取 `completed`、`progress`、`abort`。
25. 配置 Blob 提供商：Cloudflare R2 使用 wrangler.jsonc 中的 `BLOB` binding；Vercel Blob 使用 `@vercel/blob` 和 `BLOB_READ_WRITE_TOKEN`；S3 使用 `aws4fetch` 和 `S3_ACCESS_KEY_ID`、`S3_SECRET_ACCESS_KEY`、`S3_BUCKET`、`S3_REGION`。
26. 缓存路由处理器：使用 `cachedEventHandler`，设置 `maxAge: 60 * 60` 和 `getKey: event => event.path`。
27. 缓存函数：使用 `defineCachedFunction`，设置 `maxAge: 3600`、`name: 'ghStars'`、`getKey: (event, repo) => repo`。
28. 失效指定缓存：调用 `useStorage('cache').removeItem('nitro:functions:getStars:repo-name.json')`。
29. 按前缀清理缓存：调用 `useStorage('cache').clear('nitro:handlers')`。
30. 缓存 key 模式为 `${group}:${name}:${getKey(...args)}.json`，默认 `group='nitro'`，`name='handlers'|'functions'|'routes'`。
31. Cloudflare 部署配置：在 nuxt.config.ts 的 `hub` 中设置 db、kv、cache、blob 的 driver、databaseId、namespaceId、bucketName 等；NuxtHub 会自动生成 `wrangler.json`，无需手动 wrangler.jsonc。
32. 启用 observability：在 wrangler.jsonc 中设置 observability.logs 的 `enabled`、`head_sampling_rate`、`invocation_logs`、`persist`。
33. 创建 Cloudflare 资源：运行 `npx wrangler d1 create my-db` 获取 database-id，`npx wrangler kv namespace create KV` 获取 kv-namespace-id，`npx wrangler kv namespace create CACHE` 获取 cache-namespace-id，`npx wrangler r2 bucket create my-bucket` 获取 bucket-name。
34. 部署到 Cloudflare：创建 Cloudflare Workers project，链接 Git 仓库，bindings 会在构建时自动配置。
35. 配置预览环境：使用 `CLOUDFLARE_ENV=preview` 进行 preview deployments。
36. 部署到其他提供商：参考 references/providers.md 配置 Vercel 的 Postgres、Turso、Vercel Blob、Vercel KV；Netlify 的外部数据库、S3、Upstash Redis；Deno Deploy 的 Deno KV；AWS/Self-hosted 的 S3、RDS 和自定义配置。
37. 在非 Cloudflare 主机使用 D1 over HTTP：设置 `hub.db = { dialect: 'sqlite', driver: 'd1-http' }`，并配置 `NUXT_HUB_CLOUDFLARE_ACCOUNT_ID`、`NUXT_HUB_CLOUDFLARE_API_TOKEN`、`NUXT_HUB_CLOUDFLARE_DATABASE_ID`。
38. 构建时扩展 schema：使用 `nuxt.hook('hub:db:schema:extend', async ({ dialect, paths }) => { paths.push(await resolvePath(`./schema/custom.${dialect}`)) })`。
39. 构建时添加迁移目录：使用 `nuxt.hook('hub:db:migrations:dirs', (dirs) => { dirs.push(resolve('./db-migrations')) })`。
40. 构建时执行迁移后查询：使用 `nuxt.hook('hub:db:queries:paths', (paths, dialect) => { paths.push(resolve(`./seed.${dialect}.sql`)) })`。
41. 共享类型：在 `shared/types/db.ts` 中使用 `typeof users.$inferSelect` 和 `typeof users.$inferInsert` 导出 `User`、`NewUser`。
42. 启用 WebSocket：在 nuxt.config.ts 中设置 `nitro: { experimental: { websocket: true } }`。
43. 实现 WebSocket handler：在 `server/routes/ws/chat.ts` 中使用 `defineWebSocketHandler`，实现 `open`、`message`、`close`，调用 `peer.subscribe`、`peer.publish`、`peer.unsubscribe`。
44. 处理 v0.10 废弃项：`hubAI()` 改用 AI SDK with Workers AI Provider，`hubBrowser()` 改用 Puppeteer，`hubVectorize()` 改用 Vectorize，NuxtHub Admin 于 2025-12-31 日落，`npx nuxthub deploy` 改用 `wrangler deploy`。
45. 快速引用：Database 从 `hub:db` 导入 `db, schema`；KV 从 `hub:kv` 导入 `kv`；Blob 从 `hub:blob` 导入 `blob`；这些在服务端均可自动导入。

适用边界 · 注意事项

• 不使用 NuxtHub v0.10.6 或不是 Nuxt 项目时不适用。
• 只需要纯前端静态站点，且没有数据库、KV、Blob、Cache 或服务端需求时不适用。
• 依赖已废弃的 `hubAI()`、`hubBrowser()`、`hubVectorize()`、`npx nuxthub deploy` 或 NuxtHub Admin 的工作流不适用，应改用替代方案。