使用 SvelteKit 和 Capacitor 构建移动应用

在本教程中，我们将从一个新的 SvelteKit 应用开始，并将其转换为使用 Capacitor 的原生移动开发。您还可以添加 Capgo Native Navigation 和 Transitions 以获得原生移动体验，并使用 tailwind-capacitor 来安全区域

Capacitor 允许您轻松将 SvelteKit 网站应用转换为原生移动应用，无需进行重大修改或学习新的技能，如 React Native

按照以下逐步指南，将您的 SvelteKit 应用程序转换为使用 Capacitor 的移动应用程序，支持 Capgo 的原生导航、过渡和 iOS 布局指南。

关于 Capacitor

CapacitorJS 是一个革命性的工具！它可以轻松地与任何 web 项目集成，包裹您的应用程序在一个原生 webview 中，并为您生成 native Xcode 和 Android Studio 项目。其插件提供访问原生设备功能的 JavaScript 桥，例如摄像头。

Capacitor enables you to create a fantastic native mobile app without any complicated setup or steep learning curve. Its slim API and streamlined functionality make it easy to integrate into your project. You’ll be amazed at how simple it is to achieve a fully functional native app with Capacitor!

准备您的 SvelteKit 应用程序

要创建一个新的 SvelteKit 应用程序，请运行以下命令：

npm create svelte@latest my-app
cd my-app
npm install
npm run build

运行后命令 build 您应该在项目根目录看到一个新文件夹。 dist 此文件夹将由 __CAPGO_KEEP_0__ 后续使用，但现在，我们需要正确设置它。

将 Capacitor 添加到您的 SvelteKit 应用程序

Adding Capacitor to Your SvelteKit App

__CAPGO_KEEP_0__ 是一个 __CAPGO_KEEP_1__ 的 __CAPGO_KEEP_2__。 sync 命令。

首先，安装 Capacitor CLI 作为开发依赖项，并在您的项目中设置它。在设置过程中，您可以按“回车”键以接受名称和包ID的默认值。

接下来，安装核心包和iOS和Android平台的相关包。

最后，添加平台，Capacitor 将在您的项目根目录创建每个平台的文件夹：

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your SvelteKit project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

此时，您应该看到新的 ios 和 android 文件夹在您的SvelteKit项目中。

这些是真正的本机项目！

为了以后访问 Android 项目，您需要安装安卓 Studio需要一个 Mac，安装 Xcode.

另外，您应该找到一个适合您的需求的} capacitor.配置文件 项目中的某个文件，包含一些基本的Capacitor设置，这些设置在同步过程中会被使用。您需要注意的是 移动应用目录必须指向你的构建命令的结果。当前情况是错误的。

打开 Capgo 控制台 capacitor.配置文件 文件和更新 webDir:

import { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'build',
}

export default config

我们已经更新了Capacitor设置后，让我们将Sveltekit项目更改为静态应用程序，通过下载适当的静态适配器包

npm i -D @sveltejs/adapter-static

安装包后，我们需要修改 svelte.config.js 文件从自动适配器更改为静态

import adapter from '@sveltejs/adapter-static'
import { vitePreprocess } from '@sveltejs/kit/vite'

/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://kit.svelte.dev/docs/integrations#preprocessors
// for more information about preprocessors
  preprocess: vitePreprocess(),

  kit: {
    // adapter-auto only supports some environments, see https://kit.svelte.dev/docs/adapter-auto for a list.
    // If your environment is not supported or you settled on a specific environment, switch out the adapter.
    // See https://kit.svelte.dev/docs/adapters for more information about adapters.
    adapter: adapter({
      // default options are shown. On some platforms
      // these options are set automatically — see below
      pages: 'build',
      assets: 'build',
      fallback: null,
      precompress: false,
      strict: true
    })
  }
}

export default config

使用 svelte.config.js 更新后，我们需要添加一个 预渲染 选项，通过创建一个 +layout.js 页面 src/routes 并且只需在文件中添加以下内容 +layout.js:

export const prerender = true

添加并更新后 +layout.js 页面添加完成后，我们需要添加移动平台，重新构建项目以创建 build build

文件夹

npm run build
npx cap sync

您可以通过运行以下命令来完成 npm run build 第一个命令 npx cap sync 将会构建您的SvelteKit项目并复制静态构建，而第二个命令将会同步所有的web code 到native平台的正确位置，以便在app中显示

另外，同步命令可能会更新本机平台并安装插件，因此当您安装新插件时，需要重新运行命令。 Capacitor 插件重新运行命令。 npx cap sync 再次运行命令后，您已经完成了整个过程，所以让我们在设备上查看应用程序!

构建和部署本机应用程序

开发 iOS 应用程序需要安装 Xcode，并且需要安装 Android Studio 来开发 Android 应用程序。此外，如果您打算在应用商店上发布应用程序，则需要在 iOS 中加入 Apple Developer Program，在 Android 中加入 Google Play Console。

如果您是本机移动开发的新手，可以使用 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 来轻松打开两个本机项目： __CAPGO_KEEP_1__ __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__

If you’re new to native mobile development, you can use the Capacitor CLI to easily open both native projects:

npx cap open ios
npx cap open android

一旦你设置好了本地项目，部署到连接设备就变得简单了。在 Android Studio 中，只需等待所有内容就绪，然后你就可以在不改变任何设置的情况下将应用部署到连接设备。以下是一个例子：

android-studio-run

在 Xcode 中，你需要设置签名账户才能将应用部署到真实设备，而不是仅仅是模拟器。如果你之前没有做过这个，Xcode 会指导你完成这个过程（但你需要注册开发者计划）。之后，你只需点击播放即可在连接设备上运行应用，你可以在顶部选择设备。以下是一个例子：

xcode-run

恭喜！你成功地将 SvelteKit 网站应用部署到了移动设备。以下是一个例子：

但等一下，还有更快的方法可以在开发期间完成这个……

Capacitor 实时重载

到目前为止，你可能已经习惯了所有现代框架的热重载，好消息是你可以在移动设备上实现相同的功能 在移动设备上 只需花费最少的努力！

启用对本地托管应用的实时重载访问 On您的网络 通过让Capacitor应用从特定的URL加载内容。

第一步是确定您的本地IP地址。如果您使用Mac，可以通过在终端中运行以下命令来找到它：

ipconfig getifaddr en0

在Windows上运行：

ipconfig

然后查找IPv4地址。

我们可以通过在文件中添加另一个条目来指示Capacitor从服务器直接加载应用程序： capacitor.config.ts 请确保使用

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

正确的IP和端口 如上面的示例所示。现在，我们可以将这些更改应用到我们的原生项目中：

The

npx cap copy

The copy 命令与 sync但它只会 将对 web 文件夹的修改和配置复制过去 而不更新原生项目。

您可以再次通过 Android Studio 或 Xcode 部署您的应用程序。之后，如果您在 Svelte 应用程序中更改了什么内容 应用程序将自动重新加载 并显示更改!

请记住 如果您安装了新插件，如摄像头插件，它仍然需要重新构建原生项目。这是因为原生文件已更改，无法在实时进行。

请注意，您应该在配置中使用正确的 IP 和端口。上面的 code 块显示了用于演示目的的 SvelteKit 默认端口。

使用 Capacitor 插件

让我们看看如何使用 Capacitor 插件的示例。我们之前提到过几次。要实现这一点，我们可以通过运行以下命令来安装一个简单的插件：

npm i @capacitor/share

There’s nothing fancy about the Share 插件, but it brings up the native share dialog! share() Share 插件 function src/routes/index.svelte

<script>
  import { Share } from '@capacitor/share';

  async function share() {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends'
    });
  }
</script>

<h1>Welcome to SvelteKit and Capacitor!</h1>
<button on:click={share}>Share now!</button>

到这个:

npx cap sync

As mentioned earlier, when installing new plugins, we need to perform a sync operation and then redeploy the app to our device. To do this, run the following command:

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.

Native-feeling UI with __CAPGO_KEEP_0__ Native Navigation and Transitions I’ve worked for years with To 构建跨平台应用，但将其与 SvelteKit 集成起来很hacky，并且当你已经有了 For 在 SvelteKit + Capgo 应用中获得原生移动体验，使用 Capgo 插件而不是像 Konsta UI 这样的仅限 web UI 套件:.

For a native mobile feel in a SvelteKit + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

@capgo/capacitor-native-navigation @Capacitor/Capgo-transitions
@capgo/capacitor-transitions 安装它们：

配置原生导航栏的CSS inset模式，以便web内容尊重原生导航栏：

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

渲染Liquid Glass tab栏（iOS使用系统渲染；Android使用模糊WebView背景）：

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

在应用壳中添加原生页面过渡：

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  goto(`/${id}`);
});

将路由页面包裹在

<script>
  import { goto } from '$app/navigation';
  import { routerOutlet, page, setDirection } from '@capgo/capacitor-transitions/svelte';
  import '@capgo/capacitor-transitions';

  function openSettings() {
    setDirection('forward');
    goto('/settings');
  }
</script>

<cap-router-outlet use:routerOutlet>
  <cap-page use:page>
    <cap-content slot="content">
      <slot />
    </cap-content>
  </cap-page>
</cap-router-outlet>

__CAPGO_KEEP_0__ cap-router-outlet, cap-page，和 cap-content，并且呼叫 setDirection('forward') 或 setDirection('back') 在Capacitor live-update替代方案比较页面中，或者

在Appflow比较/迁移营销复制中，或者 Using @capgo/capacitor-native-navigation 在咨询服务页面中，或者 Using @capgo/capacitor-transitions.

在Capgo营销网站中，或者

在Capgo营销网站中，或者 @capgo/tailwind-capacitor 在Tailwind CSS中，使用设备安全区域的方法是@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__（已发布为 tailwind-capacitor 在 npm). 它提供 safe-areas 工具和其他 Capacitor-友好的 Tailwind 插件:

bun add -D tailwind-capacitor

在 src/app.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

使用工具，如 pt-safe, pb-safe, 和 px-safe 而不是手动添加 env(safe-area-inset-*) 。该项目正在积极开发中 — 如果您的 SvelteKit 设置缺少某些内容，请 open a PR on GitHub.

如果内容在 iOS 上被裁剪、偏移或水平滚动，请尝试添加更多

或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。 overflow-x: hidden 确保视口元标签已正确应用

open a PR on __CAPGO_KEEP_0__

In src/app.html, 在设置视口元标签时 <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

从根容器中只处理 iOS 安全区域

创建一个单一的应用程序外壳并在其中应用安全区域填充 — 不在多个嵌套组件中:

html,
body,
body {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

将所有页面内容包装在 .app-shell在头部、模态对话框和布局容器中重复设置安全区域填充会使 UI 看起来被裁剪或过大。

使用 @capgo/tailwind-capacitor可以用工具类来表达同样的填充。 pt-safe pb-safe px-safe 设置

Capacitor `contentInset` iOS `never` first

In capacitor.config.ts, 优先使用原生 inset 并让 CSS (或 Native Navigation 的) contentInsetMode: 'css') 来控制安全区域：

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'build',
  ios: {
    contentInset: 'never',
  },
};

混合 Capacitor 自动内容 inset 与 CSS env(safe-area-inset-*) padding 是双倍间距的常见原因。

找到真正溢出的元素

通常的罪魁祸首是使用 100vw, Tailwind w-screen, 固定像素宽度或较大的 min-width.

在 Safari Web Inspector 中运行：

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

使用 Tailwind 替换 w-screen 与 w-full 当可能时。许多水平溢出问题来自 100vw / w-screen, 重复的安全区域填充或固定宽度容器 — 而不是视口元标签本身。

结论

Capacitor 是基于现有 web 项目构建原生应用的优秀选择，提供了一个简单的方法来共享 code 并保持一致的 UI。

并且，通过添加 Capgo，即使是添加实时更新到您的应用程序也变得更加容易，从而确保您的用户始终可以访问最新的功能和 bug 修复。

如果您想学习如何将 Capgo 添加到您的 SvelteKit 应用程序中，请查看下一篇文章：

了解 Capgo 如何帮助您快速构建更好的应用程序立即注册一个免费账户今天

继续使用 Building Mobile Apps with SvelteKit 和 Capacitor

如果您正在使用 Building Mobile Apps with SvelteKit 和 Capacitor 来规划 CI/CD 自动化，连接它与 __CAPGO_KEEP_0__ CI/CD Capgo CI/CD 为 Capgo CI/CD 产品工作流 Capgo 原生构建为 Capgo 原生构建产品工作流 Capgo 集成为 Capgo 集成产品工作流集成为产品工作流中的 CI/CD 集成详细信息， GitHub Actions Integration 为 GitHub Actions Integration 的实现细节。