将 V0 生成的 Next.js 项目转换为本项目页面组件的流程规范;在执行 V0 项目转换、依赖清理、路径别名替换、样式迁移与验收时使用。
将 V0 生成的 Next.js 项目快速转换为本项目页面组件,保持视觉效果和功能,符合本项目开发规范。
node scripts/v0-converter.mjs <v0-project-dir> [output-name]
# 示例
node scripts/v0-converter.mjs "temp/my-v0-project" my-page
脚本会自动完成:
src/prototypes/[页面名]/.v0-tasks.md).v0-analysis.json)脚本会生成 文件,包含:
.v0-tasks.md按任务清单与本规范示例执行转换。
默认先转换为普通 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:
此时再参考 /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 特定实现:
// ❌ 需要移除
"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/[页面名]
验收要求:
# 根据报告中的依赖列表安装
pnpm add [依赖名称]
@/ 是否已转换为相对路径.v0-analysis.md 中的转换表style.css 包含 @import "tailwindcss""use client"、next/、@vercel//rules/development-guide.md/rules/debugging-guide.md/skills/default-resource-recommendations/SKILL.md