> For AI agents: the site index is available at https://www.juniortree.com/llms.txt; this page is available as Markdown at https://www.juniortree.com/docs/integrations/card-link-usage.md.
> 自动爬取链接元数据的卡片链接组件

## Page metadata

- **Published:** 2026-01-21
- **Source URL:** https://www.juniortree.com/docs/integrations/card-link-usage

# CardLink 组件使用指南

CardLink 是一个智能卡片链接组件，支持在构建时**自动爬取**链接的 Open Graph 元数据（标题、描述、图标等）。

## ✨ 特性

- 🤖 **自动爬取元数据**：从目标页面自动获取标题和描述
- ⚡ **构建时处理**：在构建时完成所有爬取，不影响运行时性能
- 🎨 **多种样式变体**：default、primary、minimal 三种风格
- 🔗 **智能后备**：爬取失败时自动使用域名作为标题
- 🌐 **外部链接标识**：自动添加外部链接图标

## 📖 基础用法

### 自动爬取（推荐）

只需提供链接，组件会自动爬取标题和描述：

```mdx
<CardLink href="https://github.com/facebook/react" />
```

效果示例：

[https://github.com/facebook/react](https://github.com/facebook/react)

### 手动指定内容

如果自动爬取的内容不理想，可以手动指定：

```mdx
<CardLink
  href="https://example.com"
  title="自定义标题"
  description="这是自定义的描述文本，可以覆盖自动爬取的内容"
/>
```

效果示例：

[自定义标题](https://example.com)

## 🎨 样式变体

### Default（默认）

```mdx
<CardLink href="https://astro.build" />
```

[https://astro.build](https://astro.build)

### Primary（强调）

```mdx
<CardLink href="https://astro.build" variant="primary" />
```

[https://astro.build](https://astro.build)

### Minimal（简约）

```mdx
<CardLink href="https://astro.build" variant="minimal" />
```

[https://astro.build](https://astro.build)

## 🔧 高级用法

### 使用自定义图标

```mdx
<CardLink
  href="https://github.com"
  icon="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387..."
/>
```

### 内部链接

对于站内链接，可以设置 `external={false}`：

```mdx
<CardLink
  href="/blog/my-post"
  title="我的文章"
  description="这是一篇内部文章"
  external={false}
/>
```

## 📦 多列布局

结合 Tailwind CSS 创建多列卡片网格：

```mdx
<div class="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose">
  <CardLink href="https://astro.build" />
  <CardLink href="https://react.dev" />
  <CardLink href="https://vuejs.org" />
  <CardLink href="https://svelte.dev" />
</div>
```

效果：

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose">
  [https://astro.build](https://astro.build)
  [https://react.dev](https://react.dev)
  [https://vuejs.org](https://vuejs.org)
  [https://svelte.dev](https://svelte.dev)
</div>

## 📋 Props 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `href` | `string` | (必需) | 跳转链接 |
| `title` | `string` | `undefined` | 手动指定标题（不指定则自动爬取） |
| `description` | `string` | `undefined` | 手动指定描述（不指定则自动爬取） |
| `icon` | `string` | `undefined` | SVG path 字符串 |
| `variant` | `'default' \| 'primary' \| 'minimal'` | `'default'` | 样式变体 |
| `external` | `boolean` | `true` | 是否在新标签页打开 |
| `class` | `string` | `undefined` | 自定义类名 |

## 🚀 性能说明

- **构建时爬取**：所有元数据在项目构建时获取，不增加运行时负担
- **智能缓存**：内置 LRU 缓存机制，避免重复请求同一 URL
- **错误处理**：爬取失败时优雅降级，使用域名作为后备标题
- **只爬取 HTTPS**：出于安全考虑，只爬取 HTTPS 链接

## 💡 最佳实践

1. **优先使用自动爬取**：让组件自动获取标题和描述，保持内容新鲜
2. **重要链接手动指定**：对于特别重要的链接，建议手动指定标题和描述
3. **合理使用变体**：使用 `primary` 突出重点链接，`minimal` 用于次要链接
4. **批量布局**：使用 grid 布局展示多个链接时，记得添加 `not-prose` 类

## 🔍 与 LinkPreview 的区别

项目中还有一个 `LinkPreview` 组件（来自 `astro-pure`），它们的区别：

| 特性 | CardLink | LinkPreview |
|------|----------|-------------|
| 布局 | 紧凑卡片 | 大型卡片（带图片） |
| 用途 | 快速链接跳转 | 内容预览展示 |
| 图片 | 不支持 | 支持 Open Graph 图片 |
| 推荐场景 | 参考资料列表 | 文章开头展示引用 |

根据你的需求选择合适的组件！