⚡

NuxtStudio设置与部署 NuxtStudio

此技能用于设置和部署Nuxt Studio，这是一个为Nuxt Content网站提供的免费开源可视化内容编辑器。它支持多种编辑器类型（如Monaco代码编辑器、TipTap可视化编辑器）、OAuth认证（GitHub/GitLab/Google）和基于Git的内容管理，可轻松配置子域名（如studio.domain.com）并部署到Cloudflare等平台。关键词：Nuxt Studio, Nuxt Content, 可视化编辑器, OAuth认证, Cloudflare部署, 内容管理, CMS, 前端开发

前端开发 0 次安装 0 次浏览 更新于 3/7/2026

name: Nuxt Studio description: 此技能应在用户询问“设置Nuxt Studio”、“配置Studio OAuth”、“部署Studio到Cloudflare”、“添加可视化编辑器到Nuxt”、“配置studio.domain.com子域名”、“Studio认证”、“Nuxt CMS”或提及可视化内容编辑、Nuxt Studio模块、TipTap编辑器、Monaco编辑器或Nuxt网站内容管理时使用。 version: 1.0.0 license: MIT

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：≥18.x 推荐
  4. Cloudflare 账户：Cloudflare 部署所需（其他平台可选）

检查 Nuxt Content 安装：

# 验证 @nuxt/content 是否已安装
grep "@nuxt/content" package.json

# 检查 nuxt.config.ts 中的内容模块
grep "modules.*content" nuxt.config.ts

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

npx nuxi module add content

安装

1. 安装 Nuxt Studio 模块

安装最新测试版（截至 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'  // 自动添加
  ]
})

3. 启动开发模式

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

npm run dev
# 或
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 预设以用于 Cloudflare
  2. **创建或更新 wrangler.toml**用于 Workers 部署（可选）
  3. 在 Cloudflare 仪表板中设置环境变量
  4. 配置自定义域名和子域名路由
  5. 通过 Cloudflare Pages 或 Workers 部署

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

快速 Cloudflare 配置

设置 Cloudflare Pages 预设：

// 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'  // 或 'monaco' 或 '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 不匹配

解决方案：

确保 OAuth 应用回调 URL 为：
https://studio.yourdomain.com/api/auth/callback/[provider]

而非：
https://yourdomain.com/api/auth/callback/[provider]

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

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

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

解决方案：

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

3. Cloudflare Pages 构建失败

错误：构建失败并显示“不兼容模块”或运行时错误

原因：未为 Cloudflare 配置 Nitro 预设

解决方案：

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

4. 登录后认证循环

错误：OAuth 成功登录后反复重定向到登录页面

原因：由于域名不匹配导致会话 Cookie 未持久化

解决方案：

  • 验证 NUXT_PUBLIC_STUDIO_URL 环境变量匹配部署 URL
  • 检查浏览器中的 Cookie 设置（必须允许第三方 Cookie 用于 OAuth）
  • 确保部署 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 UI 提交更改

生产部署

  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
  • [ ] Studio 可在子域名 URL 访问
  • [ ] 认证工作正常
  • [ ] 内容编辑和提交功能已测试

何时加载参考

在处理特定方面时加载参考文件：

  • OAuth 设置：加载 references/oauth-providers.md 以获取详细的 GitHub/GitLab/Google OAuth 应用创建
  • Cloudflare 部署：加载 references/cloudflare-deployment.md 以获取完整的 Cloudflare Pages/Workers 设置，包括 wrangler、自定义域名和环境变量
  • 编辑器配置：加载 references/editor-configuration.md 以自定义 Monaco/TipTap/表单编辑器
  • 子域名设置：加载 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 的先决条件（需要内容模块）
  • nuxt-v4：核心 Nuxt 框架知识以进行配置
  • cloudflare-worker-base：Cloudflare 部署基础
  • better-auth：如果需要自定义认证，可替代认证模式

额外资源

版本信息

  • Nuxt Studio：v1.0.0-beta.3（截至 2025 年 12 月最新）
  • Nuxt：≥3.x 必需
  • @nuxt/content：≥2.x 必需
  • Node.js：≥18.x 推荐

有关最新版本信息，请查看：https://github.com/nuxt-content/studio/releases

后续步骤：配置 Studio 后，全面测试部署，确保 OAuth 认证正常工作，并验证内容编辑和 Git 提交按预期运行。