kuroco-frontend-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kuroco フロントエンド統合パターン

Kuroco 前端整合模式

Kuroco HeadlessCMSとNuxt.js/Next.jsなどのフロントエンドフレームワークの統合パターン、およびAI自動デプロイメント。

ドキュメント参照:

/kuroco-docs

スキルを使用してKuroco公式ドキュメントを検索・参照できます。

チュートリアル: フロントエンドのデプロイ手順やサンプルサイトの構築方法は Kurocoサンプルサイトチュートリアルを参照してください。

本文介绍Kuroco HeadlessCMS与Nuxt.js/Next.js等前端框架的整合模式，以及AI自动部署方案。

文档参考: 使用

/kuroco-docs

技能可检索并查阅Kuroco官方文档。

教程: 前端部署步骤及示例网站搭建方法请参考 Kuroco示例网站教程。

サポートフレームワーク

支持的框架

フレームワーク	バージョン	推奨ユースケース
Nuxt.js 3.x	Vue 3系	新規プロジェクト（推奨）
Nuxt.js 2.x	Vue 2系	既存プロジェクト
Next.js 13+	React (App Router)	新規Reactプロジェクト
Next.js (Pages)	React (Pages Router)	既存Reactプロジェクト

框架	版本	推荐使用场景
Nuxt.js 3.x	Vue 3系	新项目（推荐）
Nuxt.js 2.x	Vue 2系	现有项目
Next.js 13+	React (App Router)	新React项目
Next.js (Pages)	React (Pages Router)	现有React项目

環境設定

环境设置

環境変数

环境变量

bash

undefined

bash

undefined

.env.local

NUXT_PUBLIC_API_BASE=https://example.g.kuroco.app NEXT_PUBLIC_API_BASE=https://example.g.kuroco.app API_ID=1

undefined

NUXT_PUBLIC_API_BASE=https://example.g.kuroco.app NEXT_PUBLIC_API_BASE=https://example.g.kuroco.app API_ID=1

undefined

プロジェクト構成

项目结构

Nuxt.js:

pages/
├── news/
│   ├── index.vue      # 一覧
│   └── [slug].vue     # 詳細 (Nuxt3)
├── login.vue
└── profile.vue
composables/
├── useAuth.ts
└── useApi.ts

Next.js (App Router):

app/
├── news/
│   ├── page.tsx       # 一覧
│   └── [slug]/page.tsx
├── login/page.tsx
└── profile/page.tsx
lib/
├── auth.ts
└── api.ts

Nuxt.js:

pages/
├── news/
│   ├── index.vue      # 列表
│   └── [slug].vue     # 详情 (Nuxt3)
├── login.vue
└── profile.vue
composables/
├── useAuth.ts
└── useApi.ts

Next.js (App Router):

app/
├── news/
│   ├── page.tsx       # 列表
│   └── [slug]/page.tsx
├── login/page.tsx
└── profile/page.tsx
lib/
├── auth.ts
└── api.ts

API設定の前提条件

API设置前提条件

1. セキュリティ設定（Cookie認証）

1. 安全设置（Cookie认证）

管理画面 → API → セキュリティ → Cookieを選択
フロントエンドとAPIドメインをサブドメイン違いに設定
- 例:
```
www.example.com
```
  と
```
api.example.com
```

管理后台 → API → 安全 → 选择Cookie
将前端与API域名设置为不同子域名
- 示例:
```
www.example.com
```
  与
```
api.example.com
```

2. CORS設定

2. CORS设置

管理画面: [API] → [セキュリティ] → [CORS設定]

CORS_ALLOW_ORIGINS:
  - http://localhost:3000
  - https://your-frontend-domain.com

CORS_ALLOW_CREDENTIALS: true

CORS_ALLOW_METHODS:
  - GET
  - POST

管理后台: [API] → [安全] → [CORS设置]

CORS_ALLOW_ORIGINS:
  - http://localhost:3000
  - https://your-frontend-domain.com

CORS_ALLOW_CREDENTIALS: true

CORS_ALLOW_METHODS:
  - GET
  - POST

認証実装

认证实现

interface LoginResponse {
  grant_token: string
  status: number
  member_id: number
}

async function login(email: string, password: string): Promise<LoginResponse> {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/login',
    {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    }
  )

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.errors?.[0]?.message || 'ログインに失敗しました')
  }

  return response.json()
}

typescript

interface LoginResponse {
  grant_token: string
  status: number
  member_id: number
}

async function login(email: string, password: string): Promise<LoginResponse> {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/login',
    {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    }
  )

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.errors?.[0]?.message || '登录失败')
  }

  return response.json()
}

ログアウト

登出

typescript

async function logout(): Promise<void> {
  await fetch('https://example.g.kuroco.app/rcms-api/1/logout', {
    method: 'POST',
    credentials: 'include'
  })
}

typescript

async function logout(): Promise<void> {
  await fetch('https://example.g.kuroco.app/rcms-api/1/logout', {
    method: 'POST',
    credentials: 'include'
  })
}

ログイン状態の確認

登录状态验证

typescript

async function checkAuth(): Promise<ProfileResponse | null> {
  try {
    const response = await fetch(
      'https://example.g.kuroco.app/rcms-api/1/profile',
      { credentials: 'include' }
    )
    if (!response.ok) return null
    return response.json()
  } catch {
    return null
  }
}

typescript

async function checkAuth(): Promise<ProfileResponse | null> {
  try {
    const response = await fetch(
      'https://example.g.kuroco.app/rcms-api/1/profile',
      { credentials: 'include' }
    )
    if (!response.ok) return null
    return response.json()
  } catch {
    return null
  }
}

会員登録

会员注册

typescript

async function signup(memberData: SignupData): Promise<void> {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/member/insert',
    {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(memberData)
    }
  )

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.errors?.[0]?.message || '登録に失敗しました')
  }
}

typescript

async function signup(memberData: SignupData): Promise<void> {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/member/insert',
    {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(memberData)
    }
  )

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.errors?.[0]?.message || '注册失败')
  }
}

Nuxt.js統合

Nuxt.js整合

詳細な実装例: references/nuxt.md を参照

クイックスタート（Nuxt 3）:

typescript

// composables/useKurocoApi.ts
export function useKurocoApi() {
  const config = useRuntimeConfig()

  async function get<T>(endpoint: string, params?: Record<string, any>): Promise<T> {
    const query = params ? `?${new URLSearchParams(params)}` : ''
    return await $fetch<T>(
      `${config.public.apiBase}/rcms-api/${config.public.apiId}/${endpoint}${query}`,
      { credentials: 'include' }
    )
  }

  return { get }
}

详细实现示例: 请参考 references/nuxt.md

快速入门（Nuxt 3）:

typescript

// composables/useKurocoApi.ts
export function useKurocoApi() {
  const config = useRuntimeConfig()

  async function get<T>(endpoint: string, params?: Record<string, any>): Promise<T> {
    const query = params ? `?${new URLSearchParams(params)}` : ''
    return await $fetch<T>(
      `${config.public.apiBase}/rcms-api/${config.public.apiId}/${endpoint}${query}`,
      { credentials: 'include' }
    )
  }

  return { get }
}

Next.js統合

Next.js整合

詳細な実装例: references/nextjs.md を参照

クイックスタート（App Router）:

typescript

// lib/api.ts
export async function apiGet<T>(endpoint: string): Promise<T> {
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_API_BASE}/rcms-api/1/${endpoint}`,
    { credentials: 'include', cache: 'no-store' }
  )
  if (!response.ok) throw new Error(`API Error: ${response.status}`)
  return response.json()
}

详细实现示例: 请参考 references/nextjs.md

快速入门（App Router）:

typescript

// lib/api.ts
export async function apiGet<T>(endpoint: string): Promise<T> {
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_API_BASE}/rcms-api/1/${endpoint}`,
    { credentials: 'include', cache: 'no-store' }
  )
  if (!response.ok) throw new Error(`API Error: ${response.status}`)
  return response.json()
}

KurocoPages統合

KurocoPages整合

KurocoPagesはKurocoが提供するフロントエンドホスティングサービス。

json

// kuroco_front.json
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

デプロイ: 管理画面 → フロントエンド → KurocoPages → GitHubリポジトリ連携

KurocoPages是Kuroco提供的前端托管服务。

json

// kuroco_front.json
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

部署: 管理后台 → 前端 → KurocoPages → 关联GitHub仓库

注意事項

注意事项

サードパーティCookie問題

第三方Cookie问题

SafariなどではサードパーティCookieがブロックされます。

解決策: APIドメインとフロントエンドドメインを同一ドメイン（サブドメイン違い）に設定

在Safari等浏览器中，第三方Cookie会被拦截。

解决方案: 将API域名与前端域名设置为同一主域名下的不同子域名

HTMLサニタイズ

HTML净化

v-html

や

dangerouslySetInnerHTML

を使用する際はXSSに注意:

typescript

import DOMPurify from 'dompurify'
const sanitizedHtml = DOMPurify.sanitize(htmlContent)

使用

v-html

或

dangerouslySetInnerHTML

时需注意XSS风险:

typescript

import DOMPurify from 'dompurify'
const sanitizedHtml = DOMPurify.sanitize(htmlContent)

AI自動デプロイ

AI自动部署

AIがKurocoサイトの登録からフロントエンドのビルド・デプロイまでを自動実行します。

詳細なワークフロー: references/ai-deployment.md を参照

AI可自动执行从Kuroco站点注册到前端构建、部署的全流程。

详细工作流: 请参考 references/ai-deployment.md

デプロイの流れ

部署流程

認証確認（whoami）
ユーザー確認（デプロイ先、モード）
サイト登録（新規の場合）
フロントエンドビルド（nuxt generate / next build / vite build）
アーティファクトアップロード（署名付きURL → S3）
デプロイ実行（KurocoFront）

身份验证（whoami）
用户确认（部署目标、模式）
站点注册（如需新建）
前端构建（nuxt generate / next build / vite build）
制品上传（预签名URL → S3）
执行部署（KurocoFront）

kuroco-frontend-integration

Original

Translation

Kuroco フロントエンド統合パターン

Kuroco 前端整合模式

目次

目录

サポートフレームワーク

支持的框架

環境設定

环境设置

環境変数

环境变量

.env.local

.env.local

プロジェクト構成

项目结构

API設定の前提条件

API设置前提条件

1. セキュリティ設定（Cookie認証）

1. 安全设置（Cookie认证）

2. CORS設定

2. CORS设置

認証実装

认证实现

ログイン

登录

ログアウト

登出

ログイン状態の確認

登录状态验证

会員登録

会员注册

Nuxt.js統合

Nuxt.js整合

Next.js統合

Next.js整合

KurocoPages統合

KurocoPages整合

注意事項

注意事项

サードパーティCookie問題

第三方Cookie问题

HTMLサニタイズ

HTML净化

AI自動デプロイ

AI自动部署

デプロイの流れ

部署流程

関連リファレンス

相关参考

関連スキル

相关技能

関連ドキュメント

相关文档