快速开始

选择接入方式

LinkFox 主要支持两种接入方式：

如果你的项目有包管理器和构建流程，使用 npm
如果你只是想在静态 HTML、CMS 或站点构建器里粘贴代码，直接跳过 npm

使用 npm 安装

适用于 React、Next.js、Nuxt、Astro、Vite 等框架。

1. 安装依赖

npm install @linkfox/web @linkfox/core

也可以使用：

pnpm add @linkfox/web @linkfox/core

yarn add @linkfox/web @linkfox/core

2. 在客户端注册 Web Components

import '@linkfox/web';

export function Sidebar() {
  return (
    <linkfox-widget
      slug="game-father"
      api-key={process.env.NEXT_PUBLIC_LINKFOX_API_KEY}
      group="game"
      title="Recommended Sites"
    />
  );
}

3. 在服务端使用 core client

import { createLinkFoxClient } from '@linkfox/core';

const linkfox = createLinkFoxClient({
  apiKey: process.env.LINKFOX_API_KEY!,
});

export async function getNetwork() {
  return linkfox.getSiteDelivery('game-father', {
    group: 'game',
    utmKey: 'ref',
    utmValue: 'server',
  });
}

使用私有 API Key 做 SSR

如果你要读取私有 LinkFox 数据，不要把 api-key 传给浏览器端组件。正确做法是在服务端使用 @linkfox/core 拉数据，再用你自己的 React 结构渲染。

Next.js Server Component 示例

import { createLinkFoxClient } from '@linkfox/core';

const linkfox = createLinkFoxClient({
  apiKey: process.env.LINKFOX_API_KEY!,
});

export async function FooterLinks() {
  const data = await linkfox.getSiteDelivery('game-father', {
    group: 'game',
    utmKey: 'ref',
    utmValue: 'footer',
  });

  return (
    <div className="inline-flex flex-wrap items-center gap-2">
      {data.items.map((item) => (
        <a key={item.id} href={item.url} target="_blank" rel="noreferrer">
          {item.name}
        </a>
      ))}
    </div>
  );
}

什么场景应该用 SSR

网络里包含私有站点或草稿站点时
不希望把 API Key 暴露到浏览器时
想完全控制 HTML 结构和样式时
浏览器端 Web Components 只适合公开数据分发

不使用 npm

适用于静态站点、CMS 模板、WordPress 代码片段、Webflow 嵌入和普通 HTML 页面。

方案 A：下载源码 zip

如果你不想发布到 npm，也不想通过 npm 安装，可以直接下载打包好的源码：

下载 LinkFox SDK 源码 zip

解压后，把这两个目录复制到你的 React 项目里：

packages/linkfox-web/src
packages/linkfox-core/src

推荐放到这样的目录结构：

src/lib/linkfox/core/*
src/lib/linkfox/web.ts

然后在客户端先注册一次 Web Components：

import '@/lib/linkfox/web';

export function Sidebar() {
  return (
    <linkfox-widget
      slug="game-father"
      api-key={process.env.NEXT_PUBLIC_LINKFOX_API_KEY}
      group="game"
      title="Recommended Sites"
    />
  );
}

如果你只想获取数据，不想直接使用组件，就只复制 linkfox-core/src：

import { createLinkFoxClient } from '@/lib/linkfox/core';

const linkfox = createLinkFoxClient({
  apiKey: process.env.LINKFOX_API_KEY!,
});

方案 B：直接引入组件脚本

<script type="module">
  import 'https://linkfox.dev/packages/linkfox-web/dist/index.js';
</script>

1. 在 HTML 中放入组件

<linkfox-grid
  slug="game-father"
  group="game"
  title="Related Products"
  max-items="4"
  utm-key="ref"
  utm-value="landing"
></linkfox-grid>

这种浏览器端接法只适合公开数据。不要把私有 api-key 直接写进页面源码。

2. 可选：增加 CSS 覆盖

<style>
  linkfox-grid.custom-links {
    --lf-background: transparent;
    --lf-border: rgba(0, 0, 0, 0.08);
    --lf-shell-padding: 0;
  }

  linkfox-grid.custom-links::part(card) {
    border-radius: 10px;
  }
</style>

如何选择

需要现成 UI 组件时，选择 @linkfox/web
只需要结构化数据时，选择 @linkfox/core
想把源码直接放进自己仓库时，选择源码 zip
只想通过 HTTP 获取 JSON 时，选择 REST API

快速开始

On this page