aceternity-ui

Aceternity UI 技能

概述

Aceternity UI 是一套高级、可用于生产环境的 React 组件库，专为 Next.js 应用打造。它提供 100 多个精美的动画交互组件，基于 Tailwind CSS 和 Framer Motion 构建。组件通过 shadcn CLI 安装，并可直接在代码库中自定义。

主要特性：

• 100 多个带动画、可用于生产环境的组件
• 专为 Next.js 13+ 构建，支持 App Router
• 完整支持 TypeScript
• Tailwind CSS v4+ 样式（CSS 优先配置；v3 也支持 JS 配置）
• Framer Motion 动画
• 支持深色模式
• 便于复制粘贴（不是 npm 包）
• 可访问完整源代码并进行自定义

前置条件：

• Next.js 13+（推荐使用 App Router）
• React 16.8+
• Tailwind CSS v4+（CSS 优先的 @import "tailwindcss" 和 @theme；也支持 v3）
• TypeScript（推荐）
• Node.js 20+，以及 bun、npm 或 pnpm

安装

初始设置

新建项目：

# Create Next.js project (bun preferred)
bunx create-next-app@latest my-app
# or: npx create-next-app@latest my-app
# or: pnpm create next-app@latest my-app

cd my-app

# Select these options:
# - TypeScript: Yes
# - ESLint: Yes
# - Tailwind CSS: Yes
# - src/ directory: Optional
# - App Router: Yes (recommended)
# - Import alias: @/* (default)

通过 shadcn CLI 初始化 Aceternity UI：

# Using bun (preferred)
bunx --bun shadcn@latest init

# Using npm
npx shadcn@latest init

# Using pnpm
pnpm dlx shadcn@latest init

# During setup:
# - Style: New York (recommended)
# - Color: Zinc (or your preference)
# - CSS variables: Yes (recommended)

配置注册表：

初始化后，更新 components.json 以添加 Aceternity 注册表：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

安装组件

使用 shadcn CLI 3.0+（命名空间注册表）：

# Install specific component
bunx shadcn@latest add @aceternity/background-beams
# or: npx shadcn@latest add @aceternity/background-beams
# or: pnpm dlx shadcn@latest add @aceternity/background-beams

# Component will be added to: components/ui/background-beams.tsx

手动安装：

如果注册表方式不起作用，请手动安装：

1. 安装所需依赖：

bun add motion clsx tailwind-merge
# or: npm install motion clsx tailwind-merge

2. 将工具函数添加到 lib/utils.ts：

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

3. 将组件代码从 ui.aceternity.com 复制到项目中

安全安装

此设置会执行多次远程代码（create-next-app、shadcn init、shadcn add）。安装前，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的软件包
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

组件类别

1. 背景与特效（28 个组件）

为主视觉区和整页布局创建惊艳的动画背景与视觉特效。

主要组件：

• Background Beams - 沿 SVG 路径移动的发光动画光束
• Background Gradient - 带过渡效果的平滑渐变背景
• Wavy Background - 动画波浪图案
• Aurora Background - 灵感源自北极光的动画渐变
• Sparkles - 粒子闪烁特效
• Meteors - 流星坠落动画
• Spotlight - 动态聚光灯特效
• Grid and Dot Backgrounds - 微妙的网格／圆点图案
• Vortex - 旋转涡流动画
• Canvas Reveal Effect - 使用画布动画展示内容

使用示例：

"use client";
import { BackgroundBeams } from "@/components/ui/background-beams";

export default function HeroSection() {
  return (
    <div className="h-screen w-full relative">
      <div className="max-w-4xl mx-auto z-10 relative p-8">
        <h1 className="text-5xl font-bold">Welcome</h1>
        <p className="text-xl mt-4">Beautiful animated backgrounds</p>
      </div>
      <BackgroundBeams />
    </div>
  );
}

适用场景：

• 需要视觉冲击力的主视觉区
• 带动画背景的落地页
• 需要增加层次感的全屏区块
• 作品集或代理机构网站
• 带行动号召的营销页面

2. 卡片组件（15 个组件）

带悬停特效、动画和 3D 变换的交互式卡片。

主要组件：

• 3D Card Effect - 带 CSS 透视效果和 3D 变换的卡片
• Card Hover Effect - 流畅的悬停动画和过渡效果
• Expandable Card - 展开后显示更多内容的卡片
• Focus Cards - 悬停时聚焦／高亮的卡片
• Card Spotlight - 跟随鼠标移动的聚光灯特效
• Glare Card - 全息眩光特效
• Wobble Card - 俏皮的摇摆动画
• Infinite Moving Cards - 自动滚动的卡片轮播
• Direction Aware Hover - 根据光标方向变化的悬停特效

使用示例：

"use client";
import { CardBody, CardContainer, CardItem } from "@/components/ui/3d-card";

export function ProductCard() {
  return (
    <CardContainer>
      <CardBody className="bg-gray-50 rounded-xl p-6">
        <CardItem translateZ="50" className="text-2xl font-bold">
          Product Title
        </CardItem>
        <CardItem translateZ="60" as="p" className="text-sm mt-2">
          Product description goes here
        </CardItem>
        <CardItem translateZ="100" className="w-full mt-4">
          <img src="/product.jpg" className="rounded-xl" alt="Product" />
        </CardItem>
      </CardBody>
    </CardContainer>
  );
}

适用场景：

• 产品展示
• 功能亮点
• 作品集项目
• 团队成员简介
• 定价方案
• 博客文章预览

3. 滚动与视差（5 个组件）

创建引人入胜的滚动动画和视差效果。

核心组件：

• 视差滚动 - 带视差滚动效果的图片
• 粘性滚动揭示 - 滚动时揭示内容
• 容器滚动动画 - 带动画的滚动容器
• 主视觉视差 - 主视觉区域的视差效果
• MacBook 滚动 - MacBook 风格的滚动交互

使用示例：

import { StickyScroll } from "@/components/ui/sticky-scroll-reveal";

const content = [
  {
    title: "Feature One",
    description: "Description of feature one...",
    content: <div>Visual content here</div>
  },
  // More items...
];

export function Features() {
  return <StickyScroll content={content} />;
}

适用场景：

• 带滚动交互的功能展示
• 叙事式布局
• 产品导览
• 带有视觉间隔的长篇内容
• 交互式时间线

4. 文本组件（10 个组件）

用于标题、主标题和交互式排版的文本动画效果。

核心组件：

• 文本生成效果 - 逐字显示文本
• 打字机效果 - 打字动画
• 翻转单词 - 单词轮换动画
• 文本悬停效果 - 悬停时的交互式文本
• 主视觉高亮 - 渐变文本高亮
• 加密文本 - 矩阵风格的加密文本效果
• 彩色文本 - 渐变动画文本

使用示例：

import { TypewriterEffect } from "@/components/ui/typewriter-effect";

const words = [
  { text: "Build" },
  { text: "amazing" },
  { text: "websites", className: "text-blue-500" }
];

export function Hero() {
  return <TypewriterEffect words={words} />;
}

适用场景：

• 主视觉标题
• 吸引注意力的标题
• 动态内容展示
• 交互式着陆页
• 动画 CTA

5. 按钮（4 个组件）

带动画和特效的增强型按钮组件。

核心组件：

• Tailwind CSS 按钮 - 一组经过样式设计的按钮
• 悬停渐变边框 - 动态渐变边框
• 移动边框 - 动态边框移动
• 状态按钮 - 带过渡效果的多状态按钮

使用示例：

import { MovingBorder } from "@/components/ui/moving-border";

export function CTAButton() {
  return (
    <MovingBorder duration={2000} className="p-4">
      <span>Get Started</span>
    </MovingBorder>
  );
}

6. 导航（5 个组件）

现代导航菜单和标签页系统。

核心组件：

• 浮动导航栏 - 浮动导航栏
• 导航菜单 - 功能齐全的导航菜单
• 标签页 - 动画标签页组件
• 可调整大小的导航栏 - 响应式导航
• 粘性横幅 - 粘性公告横幅

7. 输入与表单（3 个组件）

增强型表单输入和文件上传组件。

核心组件：

• 注册表单 - 带动画的注册表单
• 占位符与消失输入框 - 带动画占位符的输入框
• 文件上传 - 拖放式文件上传

使用示例：

import { PlaceholdersAndVanishInput } from "@/components/ui/placeholders-and-vanish-input";

export function SearchBar() {
  const placeholders = [
    "Search for anything...",
    "What are you looking for?",
    "Type to search..."
  ];

  return (
    <PlaceholdersAndVanishInput
      placeholders={placeholders}
      onChange={(e) => console.log(e.target.value)}
      onSubmit={(e) => {
        e.preventDefault();
        console.log("submitted");
      }}
    />
  );
}

8. 覆盖层与弹出层（3 个组件）

带动画的模态对话框和工具提示。

核心组件：

• 动画模态框 - 带平滑动画的模态框
• 动画工具提示 - 带进入和退出动画的工具提示
• 链接预览 - 悬停时弹出的链接预览

使用示例：

import { Modal, ModalBody, ModalContent, ModalTrigger } from "@/components/ui/animated-modal";

export function BookingModal() {
  return (
    <Modal>
      <ModalTrigger className="bg-black text-white px-4 py-2 rounded-md">
        Book Now
      </ModalTrigger>
      <ModalBody>
        <ModalContent>
          <h2>Booking Details</h2>
          {/* Modal content */}
        </ModalContent>
      </ModalBody>
    </Modal>
  );
}

9. 轮播与滑块（4 个组件）

图片滑块和轮播组件。

核心组件：

• 图片滑块 - 全屏图片滑块
• 轮播 - 标准轮播组件
• Apple 卡片轮播 - Apple 风格的卡片轮播
• 动画用户评价 - 用户评价滑块

10. 布局与网格（3 个组件）

网格布局和容器组件。

核心组件：

• 布局网格 - 动画网格布局
• Bento 网格 - 便当盒风格网格
• 容器封面 - 全屏容器

11. 数据与可视化（2 个组件）

用于展示数据和进行比较的组件。

核心组件：

• 时间线 - 动画时间线组件
• 比较 - 前后对比滑块

12. 光标与指针（3 个组件）

跟随光标的效果和交互。

核心组件：

• 跟随指针 - 跟随光标的元素
• 指针高亮 - 光标高亮效果
• 放大镜 - 放大镜效果

13. 3D 组件（2 个组件）

使用 CSS 变换实现的 3D 视觉效果。

核心组件：

• 3D 图钉 - Pinterest 风格的 3D 卡片
• 3D 跑马灯 - 3D 旋转跑马灯

14. 加载器（2 个组件）

加载动画和进度指示器。

核心组件：

• 多步骤加载器 - 多步骤加载动画
• 加载器 - 各种加载旋转图标

15. 分区与区块（3 个组件）

预构建的分区模板。

核心组件：

• 功能分区 - 功能展示模板
• 卡片 - 预先设计的卡片布局
• 主视觉分区 - 主视觉分区模板

常见模式

深色模式支持

所有 Aceternity 组件都通过 Tailwind 的深色模式类支持深色模式：

<div className="bg-white dark:bg-black text-black dark:text-white">
  {/* Content */}
</div>

响应式设计

组件默认支持响应式布局。使用 Tailwind 的响应式前缀：

<h1 className="text-2xl md:text-4xl lg:text-6xl">
  Responsive Heading
</h1>

组合组件

可以组合组件来构建复杂布局：

import { BackgroundBeams } from "@/components/ui/background-beams";
import { TypewriterEffect } from "@/components/ui/typewriter-effect";
import { MovingBorder } from "@/components/ui/moving-border";

export default function Hero() {
  return (
    <div className="h-screen relative">
      <div className="z-10 relative flex flex-col items-center justify-center h-full">
        <TypewriterEffect words={words} />
        <MovingBorder>
          <button>Get Started</button>
        </MovingBorder>
      </div>
      <BackgroundBeams />
    </div>
  );
}

最佳实践

1. 性能优化

使用 "use client" 指令 - Aceternity 组件使用 Framer Motion，需要在客户端渲染：

"use client";
import { Component } from "@/components/ui/component";

延迟加载较重的组件：

import dynamic from 'next/dynamic';

const HeavyBackground = dynamic(
  () => import('@/components/ui/background-beams'),
  { ssr: false }
);

2. 无障碍访问

添加 ARIA 标签：

<button aria-label="Open menu">
  <MenuIcon />
</button>

确保支持键盘导航：

<div role="button" tabIndex={0} onKeyDown={handleKeyDown}>
  Interactive element
</div>

3. 自定义

使用 className 覆盖样式：

<BackgroundBeams className="opacity-50" />

直接修改组件源代码 - 由于组件已复制到你的项目中，你可以编辑它们：

// components/ui/background-beams.tsx
export function BackgroundBeams({ className, myCustomProp }: Props) {
  // Customize as needed
}

4. 类型安全

使用 TypeScript 定义属性类型：

interface CardProps {
  title: string;
  description: string;
  image?: string;
}

export function Card({ title, description, image }: CardProps) {
  // Component implementation
}

故障排除

常见问题

1. “Module not found: motion”

bun add motion
# or: npm install motion

2. “cn is not defined” 确保 lib/utils.ts 存在，并包含 cn 辅助函数。

3. 组件没有动画效果 确认文件顶部有 "use client" 指令。

4. Tailwind 类不生效 确保已设置好 Tailwind。在 Tailwind v4（CSS 优先）中，globals.css 应通过一条指令导入 Tailwind：

@import "tailwindcss";

（如果你仍在使用 Tailwind v3，对应的写法是使用三条指令：@tailwind base; @tailwind components; @tailwind utilities;。）

5. 深色模式不生效 在 Tailwind v4 中，使用自定义变体在 CSS 中配置深色模式（例如，基于类的策略可使用 @custom-variant dark (&:where(.dark, .dark *));）。在 Tailwind v3 中，在 tailwind.config.ts 中设置 darkMode: "class"。

Token 效率

此技能通过以下方式显著节省 Token：

• 经过预先审核的组件选择 - 探索组件选项可节省约 3k Token
• 安装说明 - 排查设置问题可节省约 2k Token
• 组件分类 - 查找合适的组件可节省约 2k Token
• 使用示例 - 编写样板代码可节省约 2k Token
• 故障排除指南 - 排查常见问题可节省约 1k Token

预计节省：每次实现约 10k Token（减少 65-70%）

可避免的错误：

1. 缺少 motion 依赖项
2. shadcn CLI 初始化错误
3. 缺少 cn 工具函数
4. 缺少 "use client" 指令
5. 注册表配置错误
6. Next.js 配置错误（Pages Router 与 App Router 混淆）

何时加载参考资料

根据任务情境加载参考文件：

如果用户询问……	加载此参考资料
新项目设置、安装、入门	references/quick-start.md（465 行）
查找特定组件、组件分类、CLI 命令	references/component-catalog.md（635 行）
使用示例、模式、故障排除	主 SKILL.md（本文档）

参考资料摘要：

• quick-start.md - 5 分钟设置指南、第一个组件示例、故障排除、项目结构
• component-catalog.md - 100 多个组件的完整列表，包含安装命令和使用场景

其他资源

• 官方文档：https://ui.aceternity.com/docs
• 组件库：https://ui.aceternity.com/components
• Shadcn UI：https://ui.shadcn.com
• Framer Motion：https://www.framer.com/motion
• Tailwind CSS：https://tailwindcss.com

相关技能

使用此技能时，可考虑搭配以下技能：

• nextjs - Next.js 框架技能
• tailwind-v4-shadcn - Tailwind CSS v4 配置
• react-hook-form-zod - 表单验证
• clerk-auth - 身份验证
• cloudflare-nextjs - Cloudflare 部署

许可证

此技能文档采用 MIT License 提供。Aceternity UI 组件有其各自的许可协议，详情请查看 https://ui.aceternity.com。

---

最后更新：2025-12-08 版本：1.1.0 维护者：Claude Skills 维护者