Files

王冕 a27e3b8e43 feat: sync full workspace including web modules, docs, and configurations to Gitea

Optimized the root .gitignore to exclude virtual environments, node modules,
and temp folders to ensure clean and lightweight version tracking.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-09 18:12:25 +08:00

5.3 KiB

Raw Blame History

name, description

name	description
v0-project-converter	将 V0 生成的 Next.js 项目转换为本项目页面组件的流程规范；在执行 V0 项目转换、依赖清理、路径别名替换、样式迁移与验收时使用。

V0 项目转换规范

将 V0 生成的 Next.js 项目快速转换为本项目页面组件，保持视觉效果和功能，符合本项目开发规范。

核心目标

保持页面视觉一致性
移除 Next.js 特有实现
产出可在本项目中运行的页面组件

使用方式

步骤 1：运行预处理脚本

node scripts/v0-converter.mjs <v0-project-dir> [output-name]

# 示例
node scripts/v0-converter.mjs "temp/my-v0-project" my-page

脚本会自动完成：

完整复制 V0 项目到 src/prototypes/[页面名]/
分析项目结构（路径别名、Next.js 代码等）
生成 AI 工作文档（.v0-tasks.md）
生成详细数据（.v0-analysis.json）
不修改任何代码（100% 安全）

步骤 2：按任务清单完成转换

脚本会生成 .v0-tasks.md 文件，包含：

项目概况统计
6 个具体任务清单
路径别名转换参考表
依赖安装命令
验收测试步骤

按任务清单与本规范示例执行转换。

转换要点

本项目页面组件规范

默认先转换为普通 React 页面组件。只有在需求明确要求接入 Axhub / Axure 运行时能力时，才引入 forwardRef<AxureHandle, AxureProps>、useImperativeHandle 和 axure-types。

默认格式（推荐）：

/**
 * @name 页面名称
 * 
 * 参考资料：
 * - /rules/development-guide.md
 * - /skills/default-resource-recommendations/SKILL.md
 */

import './style.css';
import React from 'react';

export default function PageName() {
  // 组件逻辑
  
  return (
    // JSX 内容
  );
}

仅在以下场景才接入 Axure API：

页面需要被 Axhub / Axure 接管
需要配置面板、外部数据源、事件回调或动作触发
用户明确要求保持与现有 Axure 组件一致的接口形式

此时再参考 /rules/axure-api-guide.md，使用如下包装形式：

import React, { forwardRef, useImperativeHandle } from 'react';
import type { AxureProps, AxureHandle } from '../../common/axure-types';

const Component = forwardRef<AxureHandle, AxureProps>(function PageName(innerProps, ref) {
  useImperativeHandle(ref, function () {
    return {
      getVar: function () { return undefined; },
      fireAction: function () {},
      eventList: [],
      actionList: [],
      varList: [],
      configList: [],
      dataList: []
    };
  }, []);

  return (
    // JSX 内容
  );
});

export default Component;

移除 Next.js 特定代码

移除所有 Next.js 特定实现：

// ❌ 需要移除
"use client"                                    // Next.js 客户端组件指令，本项目不需要
import { useRouter } from 'next/navigation'    // Next.js 路由
import Image from 'next/image'                 // Next.js 图片组件
import Link from 'next/link'                   // Next.js 链接组件
import type { Metadata } from 'next'           // Next.js 元数据类型
import { Analytics } from '@vercel/analytics/next'  // Vercel 分析

// ✅ 替换为
// 删除 "use client" 指令
// 删除 useRouter 相关代码
<img> 替代 <Image>
<a> 替代 <Link>
// 删除 Metadata 和 Analytics

关于 "use client"： -本项目不使用 Next.js，所有组件都是客户端渲染

必须删除，否则会导致语法错误

路径别名转换

将 V0 的 @/ 别名转换为相对路径：

// V0 原始代码
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"

// 在 app/page.tsx 中转换为
import { cn } from "../lib/utils"
import { Button } from "../components/ui/button"

// 在 components/ui/card.tsx 中转换为
import { cn } from "../../lib/utils"

脚本生成的分析报告会提供每个文件的具体转换参考。

样式文件

/* style.css 必须以此开头 */
@import "tailwindcss";

/* 然后是原 globals.css 的内容 */
/* 保持 Tailwind V4 语法不变 */
@theme inline { ... }
@custom-variant dark (...);

依赖管理

排除 Next.js 相关依赖：

next 及所有 next-* 包
@vercel/* 包
react 和 react-dom（本项目已有）

保留其他依赖：

class-variance-authority, clsx, tailwind-merge
@radix-ui/* 组件
lucide-react, recharts, date-fns 等

验收标准

转换完成后运行验收脚本：

node scripts/check-app-ready.mjs /prototypes/[页面名]

验收要求：

状态为 READY
页面能正常渲染
无控制台错误
交互功能正常
样式显示正确

常见问题

依赖缺失

# 根据报告中的依赖列表安装
pnpm add [依赖名称]

路径错误

检查 @/ 是否已转换为相对路径
参考 .v0-analysis.md 中的转换表

样式问题

确认 style.css 包含 @import "tailwindcss"
检查 CSS 变量是否完整

Next.js 残留

搜索 "use client"、next/、@vercel/
确保全部移除或替换

参考资源

开发规范：/rules/development-guide.md
调试指南：/rules/debugging-guide.md
Tailwind CSS：/skills/default-resource-recommendations/SKILL.md

5.3 KiB Raw Blame History Unescape Escape