实战与调试 on 扎塔-Zata

下拉框里显示 _all：Base UI 与 Radix Select 的一个行为差异

Thu, 06 Aug 2026 09:30:34 +0800

一个看起来像文案错误的 bug

前几天看智能体市场页面，发现一个奇怪的现象：页面上四个筛选下拉框——来源、价格、分类、标签——触发器里齐刷刷地显示着 _all。

第一反应：文案写错了，或者翻译 key 没配。这种问题见多了，大概率是 t("xxx") 的 key 在语言包里不存在，框架把 key 原样吐了出来。

打开代码一看，不对劲。每个选项明明都写了翻译文案：

<SelectItem value="_all">{t("sourceAll")}</SelectItem>
<SelectItem value="official_template">{t("sourceOfficialTemplate")}</SelectItem>

语言包里 key 也都在。那 _all 到底是从哪冒出来的？

真相：组件库不是你以为的那个

线索藏在项目的 components/ui/select.tsx 里。这个文件的位置和命名，一看就是 shadcn/ui 的风格——而 shadcn 的 Select 底层是 Radix。但如果你真的打开它看 import：

import { Select as SelectPrimitive } from "@base-ui/react/select"
const SelectValue = SelectPrimitive.Value

是 Base UI，不是 Radix。项目不知道什么时候做过组件库迁移，目录结构原封不动地保留了下来。

这两个库的 Select.Value 看着是同一个东西，行为却完全不同：

Radix 的 SelectValue 很"贴心"：它会自动找到当前选中的 SelectItem，把它的子节点文本拿来显示。所以你只管写选项，显示的事它帮你办了。
Base UI 的 Select.Value 很"实诚"：默认把当前 value 原样渲染出来。value 是什么就显示什么——在这个项目里，就是哨兵值 _all。

翻一下它的类型定义，官方用法写得明明白白，想显示文案？自己传个函数来格式化：

// node_modules/@base-ui/react/select/value/SelectValue.d.ts
<Select.Value>
 {(value: string | null) => value ? labels[value] : 'No value'}
</Select.Value>

所以根本不存在什么文案错误。_all 是筛选状态的哨兵值，被 Base UI 原封不动地端上了桌。至于 placeholder，它只在"无值"时生效，而 _all 是一个货真价实的值，盖不住。

修复：把 value 翻译回人话

知道了根因，修法就很直接：给每个 SelectValue 传函数 children，显式地做一层 value → 文案的映射。

// 修复前：placeholder 只管无值状态，_all 会被原样渲染
<SelectValue placeholder={t("sourceAll")} />

// 修复后：显式映射
<SelectValue>
 {(value: SourceFilter) => sourceFilterLabels[value]}
</SelectValue>

映射表复用已有的翻译 key，不新增任何文案：

const sourceFilterLabels: Record<SourceFilter, string> = {
 _all: t("sourceAll"),
 official_template: t("sourceOfficialTemplate"),
 official_agent: t("sourceOfficialAgent"),
 community_agent: t("sourceCommunityAgent"),
}

分类、标签这种选项值是动态数据的，更简单，只需要特判哨兵值：

<SelectValue>
 {(value: string) => (value === "_all" ? t("allCategories") : value)}
</SelectValue>

顺手扫一遍全仓：果然不止这一处

这类"库级行为差异"导致的 bug 有个特点：它不可能只出现在一个地方。凡是「value 和展示文案不一样」的 Select，都会露底。

按这个模式扫了一遍整个前端仓库，果然收获不小——一共改了 7 个文件、13 处。项目里的哨兵值花样还不少：

_all：筛选器的"全部"占位；
__custom__ / __unlimited__：分享表单里的"自定义/不限"；
__agent_default__、model:{id}：模型选择器的特殊值；
daily / weekly：定时任务里的英文枚举，展示时应该是"每天/每周"。

也有两处不用动：value 和文案本来就相同的（比如协议选择器），以及本来就传了 children 的封装组件。扫的时候分清这两种情况，别误伤。

验证：走真实入口看一眼

改完先过静态检查（tsc --noEmit、eslint），然后写了个 Playwright 脚本走真实入口验证：起真实后端、注册真实用户、打开 /app/market，直接断言四个触发器的渲染文本。

默认状态，四个筛选器都显示中文文案：

再点开来源筛选选中「官方 Agent」，触发器显示对应文案，列表也真实地收窄到了 2 条官方 Agent：

几点收获

这个 bug 本身不大，但排查过程里有几个值得记住的点：

目录结构会骗人。 components/ui/select.tsx 长得和 shadcn/Radix 一模一样，实际却是 Base UI。迁移过组件库的项目里，API 表面相似不代表行为一致。遇到"诡异渲染"，直接去 node_modules 里读类型定义和实现，比对着代码猜快得多。
哨兵值要就地翻译。 _all、__custom__ 这类哨兵值是很好的状态设计，但必须配一层显式的 value → 文案映射，不能指望组件库帮你回取选中项文本——它可能根本没这个功能。
修一处，扫全仓。 库级行为差异是"批发生产"bug 的，按「value ≠ 展示文案」的模式全仓扫一遍，一次清干净，比等用户一个个报上来体面得多。

AI 前端调试技巧：把被遮挡翻译成尺寸约束

Thu, 25 Jun 2026 11:34:35 +0800

问题场景

用 AI 写前端时，经常遇到这样一种情况：

页面上有一个大块（比如卡片、弹窗、侧边栏），它的一部分被上层元素遮挡了，显示不完整。

你告诉 AI：“这个块被上层遮挡了，你修复一下。” 结果 AI 开始一顿操作：加 z-index、改 position、调 overflow、甚至重构整个布局。改完之后，问题可能还在，或者引入了新的样式问题。

一个更有效的说法

后来我换了一种说法，效果立刻变好了：

你先固定这个块的宽度，然后把这个块里面的 A 元素和 B 元素的宽度变小。

AI 听到这句话后，不再需要猜测"被遮挡"到底意味着什么，它只需要做两件非常具体的事：

给外层块一个固定的宽度；
把内部 A、B 两个元素的宽度调小。

问题就这样被稳定地修复了。

为什么这个方法有效

AI 处理视觉描述时，对抽象词（“遮挡”、“错位”、“不好看”）的解读空间很大，容易走偏。但如果你把问题翻译成可执行的尺寸约束，AI 的修改范围就被限定了：

固定外层宽度：先消除一个变量，避免 AI 盲目地改来改去。
缩小内部元素宽度：给出明确的调整方向，让内容在有限空间内重新排布。

这其实是把视觉问题变成了一个约束优化问题，而不是自由发挥的布局重构。

可复用的提示词模板

把这个思路抽象一下，可以得到一个通用模板：

请修复以下问题：
1. 先固定 [外层元素] 的宽度为 [具体值或百分比]；
2. 然后减小 [内部元素A] 和 [内部元素B] 的宽度，使它们不被遮挡。
不要修改 z-index、position 或 overflow，只调整宽度相关的样式。

你原本可能说的	更有效的说法
这行文字换行了	容器宽度固定为 200px，字体大小减小 1px
这个图标没对齐	把 A 的 `margin-left` 设为和 B 相同
滚动条太丑	外层固定高度，内部子元素高度减小 10px
按钮被挤下去了	容器宽度固定，按钮之间的 `gap` 减小 4px
表格列太宽	给表格容器固定宽度，指定每列的 `min-width` 和 `max-width`

总结

和 AI 协作写前端时，“被遮挡"这类描述对它来说太模糊。把它翻译成：

先固定外层宽度，再缩小内部元素宽度

AI 就能在清晰的约束下给出稳定的修复。这个技巧很小，但非常实用，值得写进你的 Vibe Coding 工具箱里。

用 AI 打造惊艳前端：从 Vibe Coding 到实战的艺术指南

Wed, 11 Jun 2025 18:30:00 +0800

🎨 引言：当创意遇见 AI

还记得那些深夜对着空白编辑器发愁的日子吗？你脑海中有一个绝妙的界面设计，但从想法到实现，往往需要数小时甚至数天的编码工作。

Vibe Coding 正在改变这一切。

这不是传统意义上的"写代码"，而是一种全新的创作方式：你描述想法，AI 生成代码，你负责审美和创意把控。就像指挥家指挥乐团，你不需要会演奏每一种乐器，但你能创造出美妙的音乐。

本文将带你深入探索 AI 辅助前端开发的世界，从工具选择到实战技巧，从开源项目学习到最佳实践，让你掌握这门新兴的艺术。

🔍 GitHub 上的宝藏项目

在开始之前，让我们先看看 GitHub 上那些闪耀的明星项目，它们代表了 AI 前端开发的最高水平。

📊 顶级开源项目一览

项目名称	⭐ Stars	核心功能	适用场景
screenshot-to-code	72.8k	截图转代码	快速复刻设计稿
claude-code-best-practice	57.4k	Claude Code 最佳实践	Vibe Coding 入门到精通
vibe-coding-cn	21.6k	中文 Vibe Coding 教程	零基础学习
easy-vibe	16.8k	系统化教程	从零到全栈
context-engineering-intro	13.4k	上下文工程	AI 编程的核心技巧

这些项目不仅是工具，更是学习 Vibe Coding 思维的绝佳教材。让我们深入分析几个关键项目。

🌟 screenshot-to-code：视觉到代码的魔法

项目地址：https://github.com/abi/screenshot-to-code

这是目前最火的 AI 前端工具之一，72.8k stars 足以说明它的价值。

工作原理

截图 → GPT-4 Vision 分析 → 生成 HTML/Tailwind/React/Vue 代码 → 实时预览

支持的技术栈

HTML + Tailwind CSS（默认）
React + Tailwind CSS
Vue + Tailwind CSS
Bootstrap
Windi CSS

实战价值

想象一下这个场景：

你在 Dribbble 上看到一个惊艳的着陆页设计
截图上传到 screenshot-to-code
30秒后，你得到了可运行的代码
再用 Claude Code 调整细节

这不再是未来，而是现在就能实现的开发流程。

🚀 claude-code-best-practice：Vibe Coding 的圣经

项目地址：https://github.com/shanraisshan/claude-code-best-practice

57.4k stars，这个项目的副标题完美诠释了 Vibe Coding 的精髓：

“from vibe coding to agentic engineering - practice makes claude perfect”

核心理念

Vibe Coding：凭感觉写代码，让 AI 处理细节
Agentic Engineering：从单次生成到系统性工程
Practice Makes Perfect：持续迭代，越用越强

关键技巧

# ❌ 错误的 Prompt
"帮我做一个好看的页面"

# ✅ 好的 Prompt
"创建一个现代化的 SaaS 着陆页，使用：
- 深色主题，主色调 #667eea
- Hero 区域包含渐变背景、CTA 按钮
- 特性展示区使用 3 列卡片布局
- 技术栈：Next.js 14 + Tailwind CSS + Framer Motion
- 参考 Vercel 官网的设计风格"

🛠️ 工具链：打造你的 AI 前端工作流

1️⃣ 核心工具选择

Claude Code - 最强编程助手

优势：

✅ 超长上下文（200K tokens）
✅ 理解复杂项目结构
✅ 直接操作文件系统
✅ 支持增量修改

适用场景：

从零开始构建项目
重构现有代码
复杂组件开发
设计系统实现

Cursor - AI 原生编辑器

优势：

✅ VS Code 的完美替代
✅ 内置 AI 对话
✅ 多文件编辑
✅ 代码补全

适用场景：

日常开发工作
快速原型迭代
团队协作

v0.dev - Vercel 的 AI UI 生成器

优势：

✅ 文字描述生成 UI
✅ 实时预览
✅ 直接部署到 Vercel
✅ 集成 shadcn/ui

适用场景：

快速原型设计
组件库探索
着陆页生成

screenshot-to-code - 设计稿转代码

优势：

✅ 支持多种框架
✅ 高度还原设计
✅ 可定制性强

适用场景：

复刻设计灵感
快速启动项目
设计师协作

2️⃣ 推荐工作流

设计灵感 → v0.dev/screenshot-to-code → 生成基础代码
 ↓
 Claude Code 优化
 ↓
 Cursor 精细调整
 ↓
 本地预览 & 部署

💡 实战案例：30分钟打造惊艳的着陆页

让我们用一个实际案例来演示完整流程。

Step 1：明确需求（2分钟）

项目：AI 写作助手着陆页
风格：现代、简洁、科技感
颜色：渐变紫色系 (#667eea → #764ba2)
必需元素：
- Hero 区：标题 + 副标题 + CTA 按钮
- 特性展示：3 个核心功能卡片
- 社会证明：用户评价
- 定价方案：3 个档位
技术栈：Next.js 14 + Tailwind CSS + Framer Motion

Step 2：快速生成（5分钟）

方案 A：使用 v0.dev

访问 v0.dev，输入：

Create a modern SaaS landing page for an AI writing assistant.

Design requirements:
- Gradient background from purple #667eea to #764ba2
- Dark theme
- Hero section with animated gradient text
- Features section with 3 cards using glassmorphism effect
- Testimonials carousel
- Pricing table with 3 tiers
- Footer with social links

Tech stack: Next.js 14, Tailwind CSS, Framer Motion

Style reference: Linear.app, Vercel.com

方案 B：使用 Claude Code

# 创建项目
npx create-next-app@latest ai-writer-landing --typescript --tailwind --app

# 进入项目
cd ai-writer-landing

# 启动 Claude Code
claude

输入详细 Prompt：

创建一个 AI 写作助手的着陆页，包含以下部分：

1. **Hero 区域**：
 - 渐变背景（#667eea → #764ba2）
 - 大标题："用 AI 释放你的写作潜能"
 - 副标题："智能改写、续写、润色，让每一篇文章都成为杰作"
 - 两个 CTA 按钮："免费试用"（主按钮）和"了解更多"（次按钮）
 - 产品截图占位区域

2. **特性展示区**：
 - 3 列网格布局
 - 每个卡片使用 glassmorphism 效果
 - 图标使用 Lucide React
 - 特性：智能改写、多种风格、实时预览

3. **社会证明区**：
 - 用户头像 + 名字 + 职位
 - 评价内容（3 条）
 - 使用卡片轮播布局

4. **定价区**：
 - 3 个定价卡片
 - 中间卡片突出显示（推荐）
 - 包含：免费版、专业版、企业版

5. **Footer**：
 - Logo + 版权信息
 - 社交媒体链接
 - 快速链接

技术要求：
- 使用 Next.js 14 App Router
- Tailwind CSS 样式
- Framer Motion 动画
- Lucide React 图标
- 响应式设计（移动端优先）
- 添加滚动动画效果
- 深色主题

Step 3：优化细节（15分钟）

添加动画效果

// components/hero.tsx
"use client";

import { motion } from "framer-motion";

export function Hero() {
 return (
 <section className="relative min-h-screen flex items-center justify-center overflow-hidden">
 {/* 渐变背景 */}
 <div className="absolute inset-0 bg-gradient-to-br from-purple-600 via-purple-700 to-indigo-800" />

 {/* 动画粒子效果 */}
 <div className="absolute inset-0">
 {[...Array(20)].map((_, i) => (
 <motion.div
 key={i}
 className="absolute w-2 h-2 bg-white rounded-full opacity-20"
 initial={{
 x: Math.random() * 100 + "%",
 y: Math.random() * 100 + "%"
 }}
 animate={{
 y: [null, Math.random() * 100 + "%"],
 opacity: [0.2, 0.8, 0.2]
 }}
 transition={{
 duration: Math.random() * 3 + 2,
 repeat: Infinity,
 ease: "linear"
 }}
 />
 ))}
 </div>

 <div className="relative z-10 text-center px-4">
 <motion.h1
 initial={{ opacity: 0, y: 20 }}
 animate={{ opacity: 1, y: 0 }}
 transition={{ duration: 0.8 }}
 className="text-5xl md:text-7xl font-bold text-white mb-6"
 >
 用 AI 释放你的
 <span className="bg-clip-text text-transparent bg-gradient-to-r from-pink-300 to-purple-200">
 写作潜能
 </span>
 </motion.h1>

 <motion.p
 initial={{ opacity: 0, y: 20 }}
 animate={{ opacity: 1, y: 0 }}
 transition={{ duration: 0.8, delay: 0.2 }}
 className="text-xl text-purple-100 mb-8"
 >
 智能改写、续写、润色，让每一篇文章都成为杰作
 </motion.p>

 <motion.div
 initial={{ opacity: 0, y: 20 }}
 animate={{ opacity: 1, y: 0 }}
 transition={{ duration: 0.8, delay: 0.4 }}
 className="flex gap-4 justify-center"
 >
 <button className="px-8 py-3 bg-white text-purple-700 rounded-full font-semibold hover:bg-opacity-90 transition-all hover:scale-105">
 免费试用
 </button>
 <button className="px-8 py-3 border border-white text-white rounded-full font-semibold hover:bg-white hover:bg-opacity-10 transition-all">
 了解更多
 </button>
 </motion.div>
 </div>
 </section>
 );
}

添加 Glassmorphism 卡片

// components/feature-card.tsx
import { motion } from "framer-motion";
import { LucideIcon } from "lucide-react";

interface FeatureCardProps {
 icon: LucideIcon;
 title: string;
 description: string;
 delay: number;
}

export function FeatureCard({ icon: Icon, title, description, delay }: FeatureCardProps) {
 return (
 <motion.div
 initial={{ opacity: 0, y: 20 }}
 whileInView={{ opacity: 1, y: 0 }}
 transition={{ duration: 0.5, delay }}
 viewport={{ once: true }}
 className="relative group"
 >
 <div className="absolute inset-0 bg-gradient-to-r from-purple-400 to-pink-400 rounded-2xl blur-xl opacity-20 group-hover:opacity-30 transition-opacity" />
 <div className="relative backdrop-blur-xl bg-white/10 rounded-2xl p-8 border border-white/20 hover:border-white/30 transition-all">
 <div className="w-12 h-12 bg-gradient-to-br from-purple-400 to-pink-400 rounded-xl flex items-center justify-center mb-4">
 <Icon className="w-6 h-6 text-white" />
 </div>
 <h3 className="text-xl font-semibold text-white mb-2">{title}</h3>
 <p className="text-purple-100">{description}</p>
 </div>
 </motion.div>
 );
}

Step 4：性能优化（5分钟）

// 添加懒加载
import dynamic from "next/dynamic";

const Testimonials = dynamic(() => import("@/components/testimonials"), {
 loading: () => <div className="h-96 animate-pulse bg-purple-900/50 rounded-2xl" />,
 ssr: false
});

// 图片优化
import Image from "next/image";

<Image
 src="/hero-screenshot.png"
 alt="AI Writer Interface"
 width={800}
 height={600}
 priority
 className="rounded-xl shadow-2xl"
/>

// 字体优化
import { Inter } from "next/font/google";
const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });

Step 5：部署上线（3分钟）

# 部署到 Vercel
npx vercel

# 或者推送到 GitHub 后自动部署
git add .
git commit -feat: add AI writer landing page
git push origin main

🎓 进阶技巧：让 AI 理解你的设计意图

技巧 1：建立设计系统文档

创建 DESIGN.md 文件，让 AI 理解你的设计规范：

# 设计系统规范

## 颜色系统
- 主色：#667eea（渐变紫）
- 次色：#764ba2（深紫）
- 强调色：#f093fb（粉色）
- 背景：#0f0f23（深色）
- 文字：#ffffff / #e0e0e0

## 排版
- 标题：Plus Jakarta Sans
- 正文：Inter
- 代码：JetBrains Mono

## 间距系统
- 使用 Tailwind 默认间距
- 卡片 padding: p-8
- 区块间距：py-20

## 组件风格
- 卡片：glassmorphism + 渐变边框
- 按钮：圆角全圆 (rounded-full)
- 输入框：半透明背景 + 白色边框

## 动画
- 持续时间：0.3s - 0.8s
- 缓动函数：ease-out
- 进入动画：fade-in + slide-up

技巧 2：使用参考链接

创建一个特性展示区，风格参考：
- Linear.app 的特性卡片
- 使用 glassmorphism 效果
- 添加 hover 时的光晕效果
- 图标使用 Lucide React

参考网址：https://linear.app

技巧 3：迭代式优化

# 第一轮
"创建一个基础的着陆页"

# 第二轮
"给 Hero 区域添加渐变背景和动画效果"

# 第三轮
"特性卡片使用 glassmorphism 风格，添加悬停效果"

# 第四轮
"优化移动端显示，确保响应式布局"

📚 学习资源推荐

GitHub 项目

awesome-vibe-coding (4.7k ⭐)
- Vibe Coding 精选资源列表
- 包含工具、教程、案例
vibesdk (5.1k ⭐)
- Cloudflare 开源的 Vibe Coding 平台
- 可自托管
codebase-to-course (4.6k ⭐)
- 将代码库转换为交互式教程
- 适合非技术背景的 Vibe Coders
ai-guide (15.6k ⭐)
- 程序员鱼皮的 AI 资源大全
- 包含 Cursor / Claude Code 教程

在线教程

Vibe Vibe - 首个系统化 Vibe Coding 开源教程
easy-vibe - 零基础到全栈实战

设计灵感网站

Dribbble - 设计师作品展示
Mobbin - 移动端 UI 参考
Land-book - 着陆页设计灵感

🎯 关键要点总结

Vibe Coding 的核心原则

原则	说明
描述清晰	用自然语言详细描述你的需求
迭代优化	不要期望一次完美，逐步改进
建立系统	创建设计规范文档，让 AI 学习你的风格
善用参考	提供设计参考链接和示例
快速验证	先生成原型，再优化细节

工具选择指南

快速原型 → v0.dev / screenshot-to-code
复杂项目 → Claude Code
日常开发 → Cursor
团队协作 → Cursor + Claude Code

避坑指南

❌ 不要做的：

提供模糊的需求（“做一个好看的页面”）
忽略技术栈限制
不建立设计规范
期望 AI 一次生成完美代码

✅ 应该做的：

提供详细的设计要求
明确技术栈和限制
建立设计系统文档
迭代式优化
学习优秀开源项目

🚀 结语：从今天开始你的 Vibe Coding 之旅

Vibe Coding 不是要取代程序员，而是让每个人都能成为创造者。

设计师可以快速实现想法
产品经理可以独立构建原型
创业者可以快速验证 MVP
开发者可以提升 10 倍效率

核心不在于你是否精通编程，而在于你是否有想法。

现在，打开你的 Claude Code 或 Cursor，开始你的第一次 Vibe Coding 吧！

📖 延伸阅读

Happy Vibe Coding! 🎨✨

如果这篇文章对你有帮助，欢迎分享给更多朋友。有问题欢迎在评论区讨论！

实战与调试 on 扎塔-Zata

下拉框里显示 _all：Base UI 与 Radix Select 的一个行为差异

一个看起来像文案错误的 bug

真相：组件库不是你以为的那个

修复：把 value 翻译回人话

顺手扫一遍全仓：果然不止这一处

验证：走真实入口看一眼

几点收获

AI 前端调试技巧：把被遮挡翻译成尺寸约束

问题场景

一个更有效的说法

为什么这个方法有效

可复用的提示词模板

更多适用场景

总结

用 AI 打造惊艳前端：从 Vibe Coding 到实战的艺术指南

🎨 引言：当创意遇见 AI

🔍 GitHub 上的宝藏项目

📊 顶级开源项目一览

🌟 screenshot-to-code：视觉到代码的魔法

工作原理

支持的技术栈

实战价值

🚀 claude-code-best-practice：Vibe Coding 的圣经

核心理念

关键技巧

🛠️ 工具链：打造你的 AI 前端工作流

1️⃣ 核心工具选择

Claude Code - 最强编程助手

Cursor - AI 原生编辑器

v0.dev - Vercel 的 AI UI 生成器

screenshot-to-code - 设计稿转代码

2️⃣ 推荐工作流

💡 实战案例：30分钟打造惊艳的着陆页

Step 1：明确需求（2分钟）

Step 2：快速生成（5分钟）

方案 A：使用 v0.dev

方案 B：使用 Claude Code

Step 3：优化细节（15分钟）

添加动画效果

添加 Glassmorphism 卡片

Step 4：性能优化（5分钟）

Step 5：部署上线（3分钟）

🎓 进阶技巧：让 AI 理解你的设计意图

技巧 1：建立设计系统文档

技巧 2：使用参考链接

技巧 3：迭代式优化

📚 学习资源推荐

GitHub 项目

在线教程

设计灵感网站

🎯 关键要点总结

Vibe Coding 的核心原则

工具选择指南

避坑指南

🚀 结语：从今天开始你的 Vibe Coding 之旅

📖 延伸阅读