> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何构建 Farcaster Mini App

在本指南中,您将学习如何使用 [Monad Farcaster Mini App 模板](https://github.com/monad-developers/monad-miniapp-template) 来构建应用。

该模板演示了所有 Mini App 能力,并允许您轻松修改,以便构建您自己的 Mini App。

## 克隆模板

您可以使用以下命令将 Mini App 模板克隆到本地机器:

```bash theme={null}
git clone https://github.com/monad-developers/monad-miniapp-template.git
```

### 安装依赖

```bash theme={null}
yarn
```

### 将 `.env.example` 复制为 `.env.local`

```bash theme={null}
cp .env.example .env.local
```

### 运行模板

```bash theme={null}
yarn run dev
```

### 在 Farcaster Embed 工具中查看应用

Farcaster 提供了一个方便的 [Embed 工具](https://farcaster.xyz/~/developers/mini-apps/embed),可用于在您发布 Mini App 之前进行检查。

不幸的是,该嵌入工具只能与远程 URL 一起使用。输入 localhost URL 是不起作用的。

作为一种变通方案,您可以使用 `cloudflared` 或 `ngrok` 等工具让本地应用可以远程访问。在本指南中我们将使用 `cloudflared`。

#### 安装 Cloudflared

```bash theme={null}
brew install cloudflared
```

有关更多安装选项,请参见 [官方文档](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)。

#### 暴露 localhost

在终端中运行以下命令:

```bash theme={null}
cloudflared tunnel --url http://localhost:3000
```

请务必为您的本地服务器指定正确的端口。

#### 在 `.env.local` 文件中设置 `NEXT_PUBLIC_URL` 环境变量

```bash theme={null}
NEXT_PUBLIC_URL=<url-from-cloudflared-or-ngrok>
```

#### 使用提供的 URL

`cloudflared` 会生成一个随机子域名并在终端打印,以供您使用。所有到该 URL 的流量都会被转发到您的本地服务器。

将提供的 URL 输入到 [Farcaster Embed 工具](https://farcaster.xyz/~/developers/mini-apps/embed) 中。

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/1.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=146bfd708a1d135908b1a0a140624091" alt="embed-tool" width="3024" height="1964" data-path="static/img/guides/farcaster-miniapp/1.png" />

让我们研究一下该模板的各个组成部分。

## 自定义 Mini App Embed

Mini App Embed 是当应用的 URL 被分享时,Mini App 出现在 feed 或聊天中的方式。

Mini App Embed 看起来像这样:

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/2.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=2bf8e35feb0b1c620e26274b29b255a2" alt="embed-preview" width="3024" height="1964" data-path="static/img/guides/farcaster-miniapp/2.png" />

您可以通过编辑文件 `app/page.tsx` 来自定义它:

```js lines title="app/page.tsx" theme={null}
...

const appUrl = env.NEXT_PUBLIC_URL;

const frame = {
  version: "next",
  imageUrl: `${appUrl}/images/feed.png`, // Embed image URL (3:2 image ratio)
  button: {
    title: "Template", // Text on the embed button
    action: {
      type: "launch_frame",
      name: "Monad Farcaster Mini App Template",
      url: appUrl, // URL that is opened when the embed button is tapped or clicked.
      splashImageUrl: `${appUrl}/images/splash.png`,
      splashBackgroundColor: "#f7f7f7",
    },
  },
};

...
```

您可以修改图片的 URL,或替换模板 `public/images` 文件夹中的图片。

在您满意所做的更改之后,请点击 Embed 工具中的 `Refetch` 以获取最新配置。

<Note>
  如果您在本地开发,请确保您的 Next.js 应用正在本地运行,且 cloudflare tunnel 处于打开状态。
</Note>

## 自定义启动画面

打开 Mini App 时,用户首先看到的是启动画面:

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/3.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=03d6c982690b1a4f48ca6c2d74bb766c" alt="splash-screen" width="2260" height="1464" data-path="static/img/guides/farcaster-miniapp/3.png" />

您可以编辑 `app/page.tsx` 文件来自定义启动画面。

```js lines title="app/page.tsx" theme={null}
...

const appUrl = env.NEXT_PUBLIC_URL;

const frame = {
  version: "next",
  imageUrl: `${appUrl}/images/feed.png`,
  button: {
    title: "Launch Template",
    action: {
      type: "launch_frame",
      name: "Monad Farcaster Mini App Template",
      url: appUrl,
      splashImageUrl: `${appUrl}/images/splash.png`, // App icon in the splash screen (200px * 200px)
      splashBackgroundColor: "#f7f7f7", // Splash screen background color
    },
  },
};

...
```

对于 `splashImageUrl`,您可以修改 URL,或替换模板 `public/images` 文件夹中的图片。

## 修改 Mini App

打开模板 Mini App,您应会看到如下界面:

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/4.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=03ac39fbe78420bbe9bfa3dec532df3c" alt="miniapp" width="3024" height="1964" data-path="static/img/guides/farcaster-miniapp/4.png" />

该界面的代码位于 `components/pages/app.tsx` 文件中:

```tsx lines title="components/pages/app.tsx" theme={null}
export default function Home() {
  const { context } = useMiniAppContext();
  return (
    // SafeAreaContainer component makes sure that the app margins are rendered properly depending on which client is being used.
    <SafeAreaContainer insets={context?.client.safeAreaInsets}>
      {/* You replace the Demo component with your home component */}
      <Demo />
    </SafeAreaContainer>
  )
}
```

您可以移除或编辑此文件中的代码来构建您自己的 Mini App。

### 访问用户上下文

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/5.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=c05e8854fddb6ecbb121a2b939a942a1" alt="user-context" width="2260" height="1464" data-path="static/img/guides/farcaster-miniapp/5.png" />

您的 Mini App 会接收关于用户的各种信息,包括 `username`、`fid`、`displayName`、`pfpUrl` 等字段。

该模板提供了一个有用的 hook `useMiniAppContext`,您可以使用它来访问这些字段:

```js lines title="components/Home/User.tsx" theme={null}
export function User() {
    const { context } = useMiniAppContext();
    return <p>{context.user.username}</p>
}
```

模板中也在 `components/Home/User.tsx` 文件中提供了类似示例。

您可以在 [此处](https://miniapps.farcaster.xyz/docs/sdk/context) 了解更多关于 Context 的信息。

### 执行 App Actions

<img src="https://mintlify.s3.us-west-1.amazonaws.com/monadfoundation-40611fb6/static/img/guides/farcaster-miniapp/composeCast.gif" style={{ marginBottom: 10, marginLeft: "auto", marginRight: "auto" }} />

Mini Apps 能够执行提升用户体验的原生 actions!

例如:

* `addFrame`:允许用户将应用保存(收藏)到一个专门的部分
* `composeCast`:允许 Mini App 提示用户使用预填的文本和媒体进行 cast
* `viewProfile`:在客户端原生 UI 中展示 Farcaster 用户的个人资料

在 [此处](https://miniapps.farcaster.xyz/docs/sdk/actions/add-miniapp) 了解更多关于 Mini App actions 的信息。

该模板提供了通过 `useMiniAppContext` hook 便捷访问这些 actions 的方式!

```js title="components/Home/FarcasterActions.tsx" theme={null}
const { actions } = useMiniAppContext();
```

有关同一功能的示例可以在 `components/Home/FarcasterActions.tsx` 文件中找到。

### 触发钱包操作

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/6.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=d57454e67fec88353104579145075726" alt="wallet-actions" width="2260" height="1464" data-path="static/img/guides/farcaster-miniapp/6.png" />

每个 Farcaster 用户都有一个支持 Monad 测试网的 Farcaster 钱包。

**Mini Apps 可以提示用户执行链上操作**!

该模板在 `components/Home/WalletActions.tsx` 文件中提供了相应示例。

```js lines title="components/Home/WalletActions.tsx" theme={null}
export function WalletActions() {
    ...

    async function sendTransactionHandler() {
        sendTransaction({
            to: "0x7f748f154B6D180D35fA12460C7E4C631e28A9d7",
            value: parseEther("1"),
        });
    }

    ...
}
```

<Warning>
  Farcaster 钱包支持多个网络。建议在触发钱包操作之前,确保连接到正确的网络。

  您可以使用 viem 的 `switchChain` 或等效方法来提示切换链。

  ```js title="components/Home/WalletActions.tsx" theme={null}
  // Switching to Monad Testnet
  switchChain({ chainId: 10143 });
  ```

  该模板在 `components/Home/WalletActions.tsx` 文件中包含相应示例。
</Warning>

## 结语

在本指南中,您了解了 Farcaster Mini Apps —— 创建具有高吸引力、高留存率和易变现应用的最简单方式!

您还了解了 Mini Apps 的关键能力,以及如何使用 [Monad Farcaster Mini App 模板](https://github.com/monad-developers/monad-miniapp-template) 来构建自己的 Mini App。

有关更多详情,请查阅 [此处](https://miniapps.farcaster.xyz/) 的官方 Mini App 文档。

### 探索更多 Farcaster Mini App 指南

<CardGroup cols={2}>
  <Card title="发送通知" href="/zh/templates/farcaster-miniapp/sending-notifications" />

  <Card title="生成自定义可分享图片" href="/zh/templates/farcaster-miniapp/generating-custom-og-images" />

  <Card title="发布 Mini App" href="/zh/templates/farcaster-miniapp/publishing-miniapp" />
</CardGroup>