使用 Capacitor 8 从零开始构建 Nuxt 移动应用

介绍

想从头开始使用 Nuxt 创建一个移动应用？本指南将带您一步一步地创建一个从一开始就配置为移动的 Nuxt 4 项目，然后使用 Capacitor 8.

通过本教程，您将拥有一个可以在模拟器上运行的工作移动应用，可以继续开发并最终发布到 App Store 和 Google Play。

所需时间： ~30 分钟

What you'll build:

A new Nuxt 4 project with the latest directory structure
静态生成配置（适用于移动端）
Capacitor 8 with essential plugins
原生 iOS 和 Android 应用
实时重载开发环境

已经有一个 Nuxt 应用了？将您的 Nuxt 应用转换为移动端而不是。

前置条件

确保您已安装这些：

Node.js 18+ (请检查 node --version)
Bun 包管理器（curl -fsSL https://bun.sh/install | bash)
Xcode (仅限macOS，用于iOS开发)
Android Studio (用于Android开发)

步骤 1：创建一个新的 Nuxt 4 项目

首先创建一个新的 Nuxt 4 项目：

bunx nuxi@latest init my-mobile-app
cd my-mobile-app
bun install

Nuxt 4 目录结构

Nuxt 4 使用了一个新的目录结构，包含 app code 在 app/ 目录：

my-mobile-app/
  app/
    assets/
    components/
    composables/
    layouts/
    middleware/
    pages/
    plugins/
    utils/
    app.vue
  public/
  server/
  nuxt.config.ts
  package.json

This structure provides better separation between app and server code.

步骤 2：配置 Nuxt 静态生成

Capacitor 需要静态 HTML/JS/CSS 文件。配置 Nuxt 静态生成 nuxt.config.ts:

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  // Enable static generation
  ssr: true,
  nitro: {
    preset: 'static',
  },
});

步骤 3：添加移动脚本

更新您的 package.json 使用移动开发脚本：

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

测试静态生成：

bun run generate

您应该看到一个 .output/public 包含静态文件的目录。

步骤 4：安装 Capacitor 8

安装 Capacitor 核心包：

bun add @capacitor/core
bun add -D @capacitor/cli

安装大多数移动应用程序所需的必备插件：

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

这些插件的功能：

@capacitor/app — 应用程序生命周期事件（前台/后台，深度链接）
@capacitor/keyboard — 原生启动屏幕控制
@capacitor/splash-screen — 键值存储（类似 localStorage 但原生）
步骤 5：初始化 capacitor — 应用程序生命周期事件（前台/后台，深度链接)
@capacitor/preferences — 原生启动屏幕控制

Step 5: Initialize Capacitor

初始化 Capacitor 以及您的项目详细信息：

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir .output/public

替换：

"My Mobile App" 用您的应用程序的显示名称
com.example.mymobileapp 用您的应用程序 ID（反向域名表示法）

这将创建 capacitor.config.ts更新它以使用插件配置：

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

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

步骤 6：添加本机平台

安装平台包：

bun add @capacitor/ios @capacitor/android

生成本机项目：

bunx cap add ios
bunx cap add android

这将创建 ios 和 android 包含本机项目的目录。

第 7 步：构建和运行

构建您的项目并同步到原生平台：

bun run mobile

在 iOS 模拟器中打开：

bun run mobile:ios

或 Android 模拟器：

bun run mobile:android

在 Xcode (iOS) 中：

从设备下拉菜单中选择一个模拟器
点击播放按钮或按 Cmd + R

在 Android Studio 中：

等待 Gradle 完成同步
从设备下拉菜单中选择一个模拟器
点击运行按钮或按 Shift + F10

第 8 步：设置 Live Reload

为了更快的开发，启用实时重载，使设备上更改立即显示。

找到你的本地IP地址：

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

创建开发Capacitor配置。更新 capacitor.config.ts:

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

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

启动开发服务器并复制配置到原生：

bun run dev &
NODE_ENV=development bunx cap copy

在Xcode/Android Studio中重建

现在，你的Nuxtcode的编辑将在设备上实时重载。

第9步：创建第一个移动屏幕

让我们创建一个移动友好的主屏幕。更新 app/app.vue:

<template>
  <NuxtPage />
</template>

创建 app/pages/index.vue:

<template>
  <main
    class="min-h-screen bg-linear-to-b from-green-500 to-green-700 flex flex-col items-center justify-center p-6 text-white"
  >
    <h1 class="text-4xl font-bold mb-4">My Mobile App</h1>
    <p class="text-xl mb-8 text-center opacity-90">
      Built with Nuxt 4 + Capacitor 8
    </p>

    <div v-if="appInfo" class="bg-white/20 rounded-lg p-4 backdrop-blur-sm mb-8">
      <p class="text-sm">
        {{ appInfo.name }} v{{ appInfo.version }}
      </p>
    </div>

    <div class="space-y-4 w-full max-w-sm">
      <button
        class="w-full py-4 px-6 bg-white text-green-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform"
        @click="handleGetStarted"
      >
        Get Started
      </button>
      <button
        class="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform"
        @click="handleShare"
      >
        Share App
      </button>
    </div>
  </main>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';

const appInfo = ref<{ name: string; version: string } | null>(null);

let backButtonListener: { remove: () => void } | null = null;

onMounted(async () => {
  // Get app info
  try {
    appInfo.value = await App.getInfo();
  } catch (e) {
    // Web fallback
    appInfo.value = { name: 'My Mobile App', version: '1.0.0' };
  }

  // Handle Android back button
  backButtonListener = await App.addListener('backButton', ({ canGoBack }) => {
    if (!canGoBack) {
      App.exitApp();
    } else {
      window.history.back();
    }
  });
});

onUnmounted(() => {
  backButtonListener?.remove();
});

function handleGetStarted() {
  // Navigate to onboarding or main app
  console.log('Get started clicked');
}

async function handleShare() {
  // We'll implement this with the Share plugin later
  console.log('Share clicked');
}
</script>

第10步：添加Tailwind CSS

为了让样式生效，添加Tailwind CSS到你的项目中：

bun add tailwindcss @tailwindcss/vite

更新 nuxt.config.ts:

import tailwindcss from '@tailwindcss/vite';

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  ssr: true,
  nitro: {
    preset: 'static',
  },

  css: ['~/assets/css/main.css'],

  vite: {
    plugins: [tailwindcss()],
  },
});

创建 app/assets/css/main.css:

@import 'tailwindcss';

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input,
textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

让我们实现分享按钮的功能：

bun add @capacitor/share

更新 app/pages/index.vue 以使用分享插件：

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';
import { Share } from '@capacitor/share';

// ... existing code ...

async function handleShare() {
  try {
    await Share.share({
      title: 'Check out this app!',
      text: 'Built with Nuxt 4 and Capacitor 8',
      url: 'https://capacitorjs.com',
      dialogTitle: 'Share with friends',
    });
  } catch (e) {
    console.log('Share cancelled or failed:', e);
  }
}
</script>

同步和重建：

bun run mobile

项目结构

您的项目现在应该像这样：

my-mobile-app/
├── android/                  # Android native project
├── ios/                      # iOS native project
├── .output/
│   └── public/              # Static build output
├── app/
│   ├── assets/
│   │   └── css/
│   │       └── main.css
│   ├── pages/
│   │   └── index.vue
│   └── app.vue
├── capacitor.config.ts       # Capacitor configuration
├── nuxt.config.ts            # Nuxt configuration
├── package.json
└── ...

下一步

您现在有一个工作的 Nuxt 移动应用。接下来要做的事情是：

必备设置

应用图标： 替换默认图标在 ios/App/App/Assets.xcassets 和 android/app/src/main/res
启动屏幕： 自定义本地项目或使用 @capacitor/splash-screen 配置
深度链接： 配置 URL 方案为您的应用

添加更多功能

相机： bun add @capacitor/camera
地理位置： bun add @capacitor/geolocation
推送通知： bun add @capacitor/push-notifications
文件系统： bun add @capacitor/filesystem

UI 增强

考虑添加 Konsta UI 为原生看起来的 iOS/Android 组件：

bun add konsta

然后更新您的 CSS 以导入主题：

@import 'tailwindcss';
@import 'konsta/theme.css';

即时更新

设置 Capgo 推送更新而无需重新提交应用商店：

bunx @capgo/cli init

故障排除

构建失败时出现“无法找到模块” 运行 bun install and try again.

iOS: “没有找到签名身份” Open Xcode, go to Signing & Capabilities, and select your development team.

Android: “SDK”位置未找到 Create android/local.properties with sdk.dir=/path/to/android/sdk

Changes not appearing on device Make sure you ran bun run mobile after making changes. For live reload, verify the IP address is correct and the dev server is running.

.output/public 是空或丢失 Make sure you configured nitro: { preset: 'static' } in nuxt.config.ts 并运行 bun run generate.

资源

准备好将您的应用程序交付？了解如何使用 Capgo 快速交付更新 — 免费账户今天。

继续 Build a Nuxt Mobile App from Scratch with Capacitor 8

如果您正在使用 Build a Nuxt Mobile App from Scratch with Capacitor 8 为 CI/CD 自动化编排做好准备，连接它 Capgo CI/CD 在 Capgo CI/CD 中， Capgo 原生构建在 Capgo 原生构建中， Capgo 集成在 Capgo 集成中， CI/CD 集成在 CI/CD 集成的实现细节中， GitHub 动作集成在 GitHub 动作集成的实现细节中。

使用 Capacitor 8 创建一个从零开始的 Nuxt 移动应用

介绍