跳过主要内容
Capgo logo
教程

使用 SvelteKit 和 Capacitor 构建移动应用

了解如何使用 SvelteKit、Capacitor 构建移动应用，并优化 Capgo 原生导航、过渡和 iOS 布局最佳实践

马丁·多纳迪厄

马丁·多纳迪厄

Content Marketer
使用 SvelteKit 和 Capacitor 构建移动应用

本教程将从新建一个 SvelteKit 应用开始，逐步过渡到使用 Capacitor 的原生移动开发。您还可以添加 Capgo 原生导航和过渡，使用 tailwind-capacitor 来安全区域。

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

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

关于 Capacitor

CapacitorJS 是一个革命性的工具！它可以轻松地与任何 web 项目集成，包裹您的应用在原生 webview 中，并为您生成原生 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

After running the build command, you should see a new dist folder at the root of your project.

This folder will be used by Capacitor later, but for now, we need to set it up correctly.

在添加 Capacitor 到您的 SvelteKit 应用程序中

为了将任何 web 应用程序打包到原生移动容器中，我们需要遵循几个初始步骤。之后，只需运行一个 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项目，需要安装 Android Studio。对于iOS，您需要Mac并安装 Xcode.

此外，您应该找到一个 capacitor.config.ts 在您的项目中，包含一些基本的Capacitor设置，用于同步过程。您需要注意的是 webDir，它必须指向您的构建命令的结果。当前它是错误的。

要修复此问题，请打开 capacitor.config.ts 文件并更新 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

在 targetLanguage":"简体中文","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["svelte.config.js","更新后，我们需要添加一个","预渲染","选项通过创建一个","+layout.js","页面到","src/routes","并只需添加以下导出到","+layout.js","添加并更新后","+layout.js","页面，我们需要添加我们的移动平台，重新构建我们的项目以创建"]]} re-build our project to create the mobile app. the mobile app. the mobile app. the mobile app. the mobile app. the mobile app. the mobile app. the mobile app.:

export const prerender = true

the mobile app. the mobile app. the mobile app. 构建 文件夹

您可以通过运行以下命令来完成：

npm run build
npx cap sync

第一个命令 npm run build 将会构建您的 SvelteKit 项目并复制静态构建，而第二个命令 npx cap sync 将同步所有的 web code 到原生平台的正确位置，以便在应用中显示。

此外，同步命令可能会更新原生平台并安装插件，因此当您安装新的 Capacitor 插件时， npx cap sync 重新运行

命令即可。

在不知不觉中，您已经完成了该过程，所以让我们在设备上看看应用！

为了开发iOS应用，您需要安装 Xcode 并且对于Android应用，您需要安装 Android Studio 。此外，如果您打算将应用发布到应用商店，则需要在iOS中注册Apple Developer Program，在Android中注册Google Play Console。

如果您是native移动开发的新手，可以使用Capacitor CLI轻松打开两种native项目：

npx cap open ios
npx cap open android

一旦您设置了native项目，部署应用到连接设备就很容易了。在Android Studio中，只需等待所有内容就绪，然后您可以在不更改任何设置的情况下将应用部署到连接设备。以下是示例：

android-studio-run

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

xcode-run

恭喜！您成功部署了SvelteKit web应用到移动设备。以下是示例：

sveltekit-mobile-app

但等一下，還有更快的方法可以在開發期間完成這項工作…

Capacitor Live Reload

現在你應該習慣了所有現代框架的熱重載功能，好消息是你可以在行動裝置上享受相同的功能 只需花費最少的努力！ 啟用對你的本地主機應用程式進行實時重載的訪問

在你的網絡上 通過讓__CAPGO_KEEP_0__應用程式從特定的URL載入內容來實現 by having the Capacitor app load the content from the specific URL.

在Windows上執行：

ipconfig getifaddr en0

然後查找IPv4地址。

ipconfig

我們可以指示__CAPGO_KEEP_0__從伺服器直接載入應用程式，通過在我們的配置中添加另一個項目來實現。

在Capacitor中啟用Live Reload功能 capacitor.config.ts file:__CAPGO_KEEP_0__

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 和端口,如示例所示。

现在，我们可以将这些更改应用到我们的本地项目中：

npx cap copy

命令与 copy 类似，但它只会 sync将 web 文件夹和配置的更改复制到本地项目中，而不更新本地项目。 您现在可以通过 Android Studio 或 Xcode 再次部署您的应用。之后，如果您在 Svelte 应用中更改了什么内容， 应用将自动重新加载

__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ and show the changes!

请注意 如果您安装了新插件，如摄像头插件，它仍然需要重建您的原生项目。这是因为原生文件发生了变化，不能在飞行中完成。

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

使用Capacitor插件

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

npm i @capacitor/share

没有什么特别的关于 Share插件，但它会弹出原生的分享对话框！现在我们只需要导入包并调用 share() 函数即可，从我们的应用程序中改变 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

点击按钮后，您可以亲眼目睹美丽的原生分享对话框的运行！

接下来，您可以使用 Capgo 导航和过渡使应用在 iOS 和 Android 上更具原生感，并解决常见的 iOS 布局问题，例如水平溢出或裁剪安全区域。

使用 Capgo 原生导航和过渡实现原生感UI

我已经工作了几年， Ionic 来构建跨平台应用，但将其与 SvelteKit 集成时需要进行hacky操作，并且当您已经有 Tailwind CSS.

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

安装:

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

使用CSS inset模式配置原生导航，以便web内容尊严原生导航栏:

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

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

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

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>

将路由页面包裹在 cap-router-outlet, cap-page,和 cap-content,并调用 setDirection('forward') 或 setDirection('back') 在导航之前。不要在原生导航拥有这些表面的情况下重复web头部或底部。

查看完整指南： 使用@capgo/capacitor-native-navigation 使用 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-转换 Using @capgo/capacitor-transitions.

在 Tailwind CSS 中使用设备安全区域

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor 有用的工具和其他 __CAPGO_KEEP_0__ 友好的 Tailwind 插件 tailwind-capacitor on npm). It provides safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

、和 src/app.css:

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

代替在各处使用 __CAPGO_KEEP_0__-类工具 pt-safe, pb-safe安全区域与 Tailwind px-safe 在 Tailwind CSS 中使用设备安全区域 env(safe-area-inset-*) by hand. 该项目正在积极开发中 — 如果您的 SvelteKit 设置中缺少某些内容, 在 GitHub 上打开一个 PR.

iOS 布局问题修复 (视口、安全区域和水平溢出)

如果内容在 iOS 上看起来被裁剪、偏移或水平滚动, overflow-x: hidden 或仅仅调整视口标签通常无法解决问题。按照以下顺序检查这些内容

确保视口元标签已正确应用

在 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);
}

创建一个单一的应用 shell 并在其中应用安全区域填充 — 不要在多个嵌套组件中进行填充: .app-shell将所有页面内容包装在内。重复的安全区域填充在头部、模态窗口和布局包装器中通常会使 UI 看起来被裁剪或过大。

With @capgo/tailwind-capacitor,您可以使用类似于 pt-safe pb-safe px-safe 的工具来实现相同的填充效果

设置Capacitor iOS contentInset 为 never 首先

,更倾向于使用原生 inset disabled 并让 CSS (或 Native Navigation 的) capacitor.config.ts控制安全区域： contentInsetMode: 'css'混合__CAPGO_KEEP_0__的自动内容 inset 与 CSS

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) __CAPGO_KEEP_0__

找到真正的溢出元素

通常的罪魁祸首是使用 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 CI/CD 为Capgo CI/CD中的产品工作流程 Capgo 原生构建 为产品工作流程在 Capgo 原生构建中 Capgo 集成 为产品工作流程在 Capgo 集成中 CI/CD 集成 CI/CD 集成的实现细节 GitHub 动作集成 为 GitHub 动作集成的实现细节

Capacitor应用的实时更新

当web层bug处于活跃状态时，通过Capgo将修复推送到应用，而不是等待几天的应用商店审批。用户在后台接收更新，而原生变化仍然在正常审批路径中。

立即开始

博客最新文章

Capgo为您提供创建真正专业的移动应用所需的最佳见解。

Capacitor应用中的双向通信
开发 移动应用 +1
2025年4月26日

Capacitor应用的双向通信

避免的5种OTA更新常见错误
开发 安全 +1
2025年4月13日

避免的5种OTA更新常见错误

移动应用实时更新的5种安全最佳实践
开发 Mobile +1
2025年1月14日

移动应用实时更新的5个安全最佳实践

查看我们博客中的所有内容