nuxt-studio

Nuxt Studio 设置与部署

概述

Nuxt Studio 是一款免费、开源的 Nuxt Content 网站可视化内容编辑器，可直接在生产环境中编辑内容。它提供多种编辑器类型（Monaco 代码编辑器、TipTap 可视化所见即所得编辑器、基于表单的编辑器）、OAuth 身份验证（GitHub/GitLab/Google），以及支持提交集成的基于 Git 的内容管理。

主要用途：为现有 Nuxt Content 网站添加可视化 CMS 功能，通常部署到 studio.domain.com 或 cms.domain.com 之类的子域名。

何时使用此技能

在以下情况使用此技能：

• 首次为 Nuxt Content 网站设置 Nuxt Studio
• 配置 Studio 访问所需的 OAuth 身份验证
• 将 Studio 部署到 Cloudflare Pages 或 Workers，并使用自定义子域名
• 排查 Studio 身份验证、构建或部署问题
• 配置编辑器类型或自定义 Studio 行为
• 将 Studio 集成到现有 Nuxt v3/v4 应用中

前置条件检查

在开始设置 Studio 之前，请确认满足以下要求：

1. Nuxt 版本：≥3.x（Studio 需要 Nuxt 3）
2. @nuxt/content 模块：≥2.x（必需依赖）
3. Node.js：建议使用 ≥20.x
4. Cloudflare 账户：部署到 Cloudflare 时必需（其他平台可选）

检查 Nuxt Content 是否已安装：

# Verify @nuxt/content is installed
grep "@nuxt/content" package.json

# Check nuxt.config.ts for content module
grep "modules.*content" nuxt.config.ts

如果尚未安装 Nuxt Content，请先安装：

npx nuxi module add content

安装

1. 安装 Nuxt Studio 模块

安装最新的 beta 版本（截至 2025 年 12 月为 v1.0.0-beta.3）：

npx nuxi module add nuxt-studio@beta

这会将 @nuxt/studio 添加到 devDependencies，并在 nuxt.config.ts 中配置该模块。

2. 验证模块配置

检查 nuxt.config.ts 是否包含 Studio 模块：

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
    '@nuxt/studio'  // Added automatically
  ]
})

3. 启动开发模式

运行开发服务器，在本地测试 Studio：

npm run dev
# or
bun dev

在开发模式下，通过 http://localhost:3000/_studio 访问 Studio。

OAuth 身份验证设置

生产环境部署需要为 Studio 配置 OAuth 身份验证。请选择一个提供商：

支持的提供商

• GitHub OAuth：适用于公开仓库和托管在 GitHub 上的项目
• GitLab OAuth：适用于自托管的 GitLab 实例
• Google OAuth：适用于各种配置的通用选项

快速配置 OAuth

如需各提供商的详细 OAuth 设置说明，请加载 references/oauth-providers.md。

环境变量格式（适用于所有提供商）：

# GitHub
NUXT_OAUTH_GITHUB_CLIENT_ID=your_client_id
NUXT_OAUTH_GITHUB_CLIENT_SECRET=your_client_secret

# GitLab
NUXT_OAUTH_GITLAB_CLIENT_ID=your_client_id
NUXT_OAUTH_GITLAB_CLIENT_SECRET=your_client_secret

# Google
NUXT_OAUTH_GOOGLE_CLIENT_ID=your_client_id
NUXT_OAUTH_GOOGLE_CLIENT_SECRET=your_client_secret

回调 URL 格式：

https://studio.yourdomain.com/api/auth/callback/[provider]

将 [provider] 替换为：github、gitlab 或 google。

如需 OAuth 应用的完整创建步骤，请参阅 references/oauth-providers.md。

部署到 Cloudflare

Studio 在 Cloudflare Pages 和 Workers 上运行效果出色。以下情况适合部署到 Cloudflare：

• 无服务器边缘部署
• 自定义子域名路由（例如 studio.domain.com）
• 通过控制面板管理环境变量
• 根据 Git 自动构建

Cloudflare 设置概览

1. 在 nuxt.config.ts 中配置 Nitro preset，以使用 Cloudflare
2. 为 Workers 部署创建或更新 wrangler.toml（可选）
3. 在 Cloudflare 控制面板上设置环境变量
4. 配置自定义域名和子域名路由
5. 通过 Cloudflare Pages 或 Workers 进行部署

如需完整的 Cloudflare 部署说明，请加载 references/cloudflare-deployment.md。

快速配置 Cloudflare

设置 Cloudflare Pages preset：

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', '@nuxt/studio'],

  nitro: {
    preset: 'cloudflare-pages'
  }
})

如需使用自定义子域名路由部署到 Workers，请参阅 references/cloudflare-deployment.md。

编辑器类型

Studio 提供三种编辑器类型，可按内容类型进行配置：

1. Monaco 编辑器：用于编辑 markdown、YAML、JSON 的代码编辑器
2. TipTap 编辑器：支持 MDC 组件的可视化所见即所得编辑器（默认）
3. 表单编辑器：用于 YAML/JSON 文件的架构驱动表单

配置默认编辑器

// nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    editor: {
      default: 'tiptap'  // or 'monaco' or 'form'
    }
  }
})

如需详细的编辑器配置选项，请加载 references/editor-configuration.md。

子域名配置

在生产环境中将 Studio 部署到子域名：

常见模式：

• studio.yourdomain.com
• cms.yourdomain.com
• edit.yourdomain.com
• admin.yourdomain.com

DNS 设置

1. 在 DNS 服务商处添加 CNAME 记录
2. 将子域名指向 Cloudflare Pages 部署
3. 在 Cloudflare Pages 设置中配置自定义域名

如需完整的 Cloudflare 子域名设置说明，请加载 references/subdomain-setup.md。

最常见的 5 种错误

1. OAuth 重定向 URI 不匹配

错误：身份验证循环或出现“redirect_uri_mismatch”错误

原因：OAuth 应用回调 URL 与实际部署 URL 不匹配

解决方案：

Ensure OAuth app callback URL is:
https://studio.yourdomain.com/api/auth/callback/[provider]

Not:
https://yourdomain.com/api/auth/callback/[provider]

2. 找不到模块：@nuxt/studio

错误：Cannot find module '@nuxt/studio'

原因：Studio 模块未安装或安装不正确

解决方案：

npx nuxi module add nuxt-studio@beta
# or
npm install -D @nuxt/studio

3. Cloudflare Pages 构建失败

错误：构建失败，并出现“Incompatible module”或运行时错误

原因：未针对 Cloudflare 配置 Nitro 预设

解决方案：

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages'
  }
})

4. 登录后陷入身份验证循环

错误：OAuth 成功后不断重定向到登录页面

原因：由于域名不匹配，会话 Cookie 未能持久保存

解决方案：

• 确认 NUXT_PUBLIC_STUDIO_URL 环境变量与部署 URL 匹配
• 检查浏览器中的 Cookie 设置（OAuth 必须允许第三方 Cookie）
• 确保部署 URL 使用 HTTPS（而不是 HTTP）

5. 子域名路由无法正常工作

错误：Studio 加载在主域名上，而不是子域名上

原因：DNS/wrangler 配置不正确

解决方案：

• 确认 CNAME 记录指向 Cloudflare Pages
• 检查 Cloudflare 控制面板中的自定义域名配置
• 对于 Workers：确认 wrangler.toml 中的路由配置

如需完整的错误目录和解决方案，请加载 references/troubleshooting.md。

使用模板

此技能包含可用的配置模板：

• templates/nuxt.config.ts：完整的 Studio 模块配置
• templates/wrangler.toml：Cloudflare Workers 部署配置
• templates/studio-auth-github.ts：GitHub OAuth 实现
• templates/studio-auth-gitlab.ts：GitLab OAuth 实现
• templates/studio-auth-google.ts：Google OAuth 实现

可将这些模板用作 Studio 设置的起点。

开发工作流

本地开发

1. 安装 Studio 模块：npx nuxi module add nuxt-studio@beta
2. 启动开发服务器：npm run dev
3. 访问 Studio：http://localhost:3000/_studio
4. 通过可视化界面编辑内容
5. 在 Studio 界面中提交更改

生产部署

1. 配置 OAuth 提供商（GitHub/GitLab/Google）
2. 在部署平台上设置环境变量
3. 为目标平台配置 Nitro 预设
4. 部署到 Cloudflare Pages/Workers 或其他平台
5. 设置自定义子域名
6. 测试身份验证和内容编辑

验证清单

将 Studio 部署到生产环境之前：

• 已安装并配置 Nuxt Content（≥v2.x）
• Nuxt 版本 ≥3.x
• 已安装 @nuxt/studio 模块
• 已使用有效凭据配置 OAuth 提供商
• 环境变量设置正确
• 已针对部署平台配置 Nitro 预设
• 已配置自定义子域名 DNS
• 回调 URL 与部署 URL 匹配
• 可通过子域名 URL 访问 Studio
• 身份验证正常工作
• 已测试内容编辑和提交功能

何时加载参考资料

处理特定方面时，请加载相应的参考文件：

• OAuth 设置：加载 references/oauth-providers.md，了解如何详细创建 GitHub/GitLab/Google OAuth 应用
• Cloudflare 部署：加载 references/cloudflare-deployment.md，查看 Cloudflare Pages/Workers 的完整设置，包括 wrangler、自定义域名和环境变量
• 编辑器配置：加载 references/editor-configuration.md，了解如何自定义 Monaco/TipTap/Form 编辑器
• 子域名设置：加载 references/subdomain-setup.md，查看 DNS 和路由配置
• 故障排查：加载 references/troubleshooting.md，查看全面的错误解决方案和调试方法

实用脚本

使用随附的脚本执行常见操作：

• scripts/check-prerequisites.sh：验证 Nuxt Content 和版本要求
• scripts/validate-config.sh：检查 nuxt.config.ts 中的 Studio 配置
• scripts/test-oauth.sh：测试 OAuth 环境变量设置

运行脚本：

bash $CLAUDE_PLUGIN_ROOT/skills/nuxt-studio/scripts/script-name.sh

与其他技能集成

此技能可与以下技能配合使用：

• nuxt-content：Studio 的前置条件（需要 content 模块）
• nuxt-v4：用于配置的 Nuxt 核心框架知识
• cloudflare-worker-base：Cloudflare 部署基础知识
• better-auth：需要自定义身份验证时的替代身份验证模式

其他资源

• Nuxt Studio 仓库：https://github.com/nuxt-content/studio
• Nuxt Content 文档：https://content.nuxt.com
• Cloudflare Pages：https://pages.cloudflare.com
• OAuth 文档：GitHub/GitLab/Google 开发者文档

版本信息

• Nuxt Studio：v1.0.0-beta.3（截至 2025 年 12 月的最新版本）
• Nuxt：需要 ≥3.x
• @nuxt/content：需要 ≥2.x
• Node.js：建议 ≥20.x

如需了解最新版本信息，请查看：https://github.com/nuxt-content/studio/releases

---

后续步骤：配置好 Studio 后，全面测试部署，确保 OAuth 身份验证正常运行，并验证内容编辑和 Git 提交功能符合预期。