Next.js Apple图标设置：2026年App Router指南

如果你曾经在 iPhone 上打开你的 Next.js 网站，并尝试将其添加到主屏幕时看到了一个空白的灰色方块，那么你缺少的就是 Apple touch icon。浏览器标签页上的 favicon 可能看起来正常，但 iOS 使用的是单独的文件——而 Next.js 有特定的方式来提供这个文件。

本指南将带你完成 Next.js Apple 图标设置，使用 App Router 基于文件的元数据系统。无需自定义 API 路由，也无需在 _document.tsx 中手动编写 <link> 标签——只需将文件放入正确的文件夹即可。

前提条件

在开始之前，请确保你具备：

一个使用 App Router 的 Next.js 项目（版本 13.2 或更高）。
一个用于图标的图片文件。Apple 建议 touch icon 使用 180×180 的 PNG，但稍后我们会详细说明。
对项目的 app/ 目录有基本了解。

步骤 1：准备 Apple Touch Icon

Apple 的 touch icon 是一个 PNG 文件，当用户将你的网站添加到主屏幕时，iOS 会使用它。推荐尺寸为 180×180 像素，但你也可以为 iPad Pro 提供 167×167，为旧款 iPad 提供 152×152。不过，iOS 会自动缩放 180×180 的图标，因此你只需要一个文件即可。

如果你没有现成的图标，可以使用类似 Mzu favicondl 的工具从你的 logo 生成一个。它可以导出带有正确透明度和内边距的 180×180 PNG。

步骤 2：将文件放入 App 目录

在 Next.js App Router 中，你可以直接将 apple-icon.png（或 apple-icon.jpg）放在 app/ 目录中。Next.js 会自动检测它，并在你的网站根目录提供该文件。该文件应放在与 layout.tsx 相同的文件夹中——通常是 app/。

以下是一个示例文件夹结构：

app/
├── layout.tsx
├── page.tsx
├── apple-icon.png
└── icon.png

就这样。Next.js 会自动在页面头部生成相应的 <link rel='apple-touch-icon'> 标签。你无需手动编写任何 HTML。

步骤 3：验证生成的 HTML

要确认图标是否正常提供，请运行开发服务器并检查页面源代码。你应该会看到类似这样的行：

<link rel='apple-touch-icon' href='/apple-icon.png' sizes='180x180' type='image/png'/>

如果你没有看到它，请检查文件名是否完全为 apple-icon.png，并且位于正确的目录中。Next.js 在 Linux 和 macOS 上区分大小写。

步骤 4：使用 Metadata API 进行更多控制

如果你需要指定多个图标，或者希望以编程方式设置它们，可以在 layout 中使用 metadata 导出。当你需要为不同路由使用不同图标，或者想为 Android 添加 maskable 图标时，这会很有用。

以下是在 app/layout.tsx 中的示例：

import type { Metadata } from 'next';

export const metadata: Metadata = {
  icons: {
    apple: [
      { url: '/apple-icon.png', sizes: '180x180', type: 'image/png' },
    ],
  },
};

这种方法让你完全控制 rel、sizes 和 type 属性。你也可以使用它来为 Android PWA 添加 maskable 图标，尽管那是另一个话题。

常见陷阱

以下是你可能会遇到的一些问题：

文件未找到：仔细检查文件名。它必须是 apple-icon.png 或 apple-icon.jpg。Next.js 不会识别 apple-touch-icon.png。
缓存问题：iOS 会积极缓存图标。如果你更改了图标但看不到更新，请尝试清除 Safari 的缓存或使用其他设备。
尺寸错误：Apple 推荐 180×180，但如果你使用不同尺寸，iOS 会进行缩放。缩放可能导致模糊，因此请坚持使用推荐尺寸。
透明度：iOS 不支持 Apple touch icon 中的透明度。如果你的 PNG 有透明区域，它们会显示为黑色。确保你的图标具有纯色背景。

结论

一旦你了解了基于文件的约定，在 Next.js 中设置 Apple touch icon 就很简单了。将适当尺寸的 PNG 放入 app/ 文件夹，Next.js 会处理其余部分。对于更高级的场景，metadata API 提供了编程控制。

如果你需要生成图标本身，可以尝试 Mzu favicondl 从你的 logo 创建所有所需尺寸。有关 Next.js 中 favicon 设置的更全面介绍，请查看我们的 Next.js Favicon 指南。

查看文档要求

Next.js 在其元数据文件约定中记录了 favicon 和应用程序图标。