Saltar al contenido principal

Integrar una aplicación Flutter en tu proyecto iOS

Aprende cómo integrar una aplicación Flutter en tu proyecto iOS existente.

Los componentes de la UI de Flutter se pueden añadir gradualmente a tu aplicación iOS existente utilizando paquetes Swift.

Requisitos previos

#
  • Flutter 3.44 o posterior
  • Xcode 15.0 o posterior

Migrar desde la integración heredada (si corresponde)

#

Si ya has integrado Flutter en tu aplicación iOS utilizando CocoaPods o frameworks embebidos, primero debes eliminar esa integración antes de seguir las instrucciones de Swift Package Manager a continuación.

Expandir para ver las instrucciones de migración desde la integración con CocoaPods

Si tu aplicación se integró previamente utilizando CocoaPods, primero debes eliminar el código de instalación de Flutter de tu Podfile.

  1. Eliminar el código de instalación de Flutter de tu Podfile

    MyApp/Podfile
    ruby
    flutter_application_path = '../my_flutter'
load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')
​
install_all_flutter_pods(flutter_application_path)
​
flutter_post_install(installer) if defined?(flutter_post_install)

  2. Ejecuta pod install.

Expandir para ver las instrucciones de migración desde la integración con frameworks embebidos

Si tu aplicación se integró previamente utilizando frameworks generados por el comando flutter build ios-framework, primero debes eliminar los frameworks de tu proyecto Xcode.

  1. Navega a la pestaña General de tu target y elimina todos los frameworks y bibliotecas relacionados con Flutter en la sección Frameworks, Libraries, and Embedded Content.

    Esto incluye los archivos App.xcframework, Flutter.xcframework, FlutterPluginRegistrant.xcframework y los archivos xcframework de cualquier plugin de Flutter.

  2. Eliminar el pod de Flutter de tu Podfile

    MyApp/Podfile
    ruby
    pod 'Flutter', :podspec => '/path/to/MyApp/Flutter/[build mode]/Flutter.podspec'

  3. Ejecuta pod install.

La guía de integración heredada se conserva como referencia, pero no recibirá mantenimiento continuo.

Organizar tus proyectos uno respecto del otro

#

Esta guía asume que tu aplicación iOS existente y tu aplicación o módulo Flutter residen en directorios hermanos. Si tienes una estructura de directorios diferente, deberás ajustar las rutas relativas de los ejemplos en consecuencia.

La estructura de directorios del ejemplo se asemeja a la siguiente:

  • my_flutter_app/
    • ios/
    • lib/
      • main.dart
  • MyNativeApp/
    • MyNativeApp.xcodeproj/
  • my_flutter_app/
    • .ios/
    • lib/
      • main.dart
  • MyNativeApp/
    • MyNativeApp.xcodeproj/

Integrar con Swift Package Manager

#

  1. Compilar el paquete Swift FlutterNativeIntegration

    Dentro de tu aplicación o módulo Flutter, ejecuta el siguiente comando:

    flutter build swift-package --platform ios

    Esto generará los siguientes directorios:

    • my_flutter_app/build/ios/SwiftPackages/
      • FlutterNativeIntegration/(Un paquete Swift)
      • Scripts/(Directorio de scripts y otros archivos necesarios)

    Opcionalmente, puedes cambiar la ubicación de esta salida con la bandera --output.

  2. Añadir FlutterNativeIntegration a tu proyecto Xcode

    1. Abre tu aplicación iOS existente en Xcode.

    2. En el Project navigator, haz clic derecho en tu proyecto y selecciona Add Files to "MyNativeApp"...

    3. Navega hasta el paquete Swift generado FlutterNativeIntegration y selecciónalo, luego haz clic en Add.

    4. Selecciona Reference files in place y haz clic en Finish.

    5. En el File inspector, verifica que la Location sea Relative to Project. Si no lo es, deberás mover el directorio de salida de Flutter para que sea un directorio hermano de tu aplicación nativa.

      Ubicación relativa de FlutterNativeIntegration mostrada en el inspector de archivos de Xcode.

      Ubicación relativa de FlutterNativeIntegration mostrada en el inspector de archivos de Xcode.

    6. Navega a la pestaña General de tu target y añade FlutterNativeIntegration bajo Frameworks, Libraries, and Embedded Content. FlutterNativeIntegration bajo Frameworks, Libraries, and Embedded Content.

      FlutterNativeIntegration bajo Frameworks, Libraries, and Embedded Content.

  3. Añadir configuraciones de compilación (Build Settings)

    1. En la pestaña Build Settings, establece la ubicación del directorio de salida del paquete Swift de la aplicación Flutter:

      FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/ios/SwiftPackages

    2. Para configuraciones personalizadas, establece el modo de compilación de Flutter.

      Flutter admite tres modos de compilación: Debug, Profile y Release. El modo de compilación se determina utilizando la variable CONFIGURATION. Si tu configuración no coincide con una de estas, puedes establecer la configuración de compilación FLUTTER_BUILD_MODE en uno de estos valores.

      Establecer `FLUTTER_BUILD_MODE` para configuraciones personalizadas bajo **Build Settings**.

      Establecer FLUTTER_BUILD_MODE para configuraciones personalizadas bajo Build Settings.

    3. (Opcional) Permitir que Xcode vuelva a compilar tu aplicación Flutter.

      Añade los siguientes ajustes de compilación a tu target para permitir que Xcode vuelva a compilar tu aplicación Flutter como parte de su proceso de compilación. Esto te permite realizar cambios en tu aplicación Flutter sin necesidad de volver a ejecutar el comando flutter build swift-package. Esto requiere que Flutter esté instalado en la máquina.

      FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
ENABLE_USER_SCRIPT_SANDBOXING=NO

  4. Añadir script de ejecución de pre-acción al Scheme

    1. Abre Product > Scheme > Edit Scheme... > Build (en la barra lateral izquierda) > Pre-action > + > New Run Script Action

    2. Selecciona tu proyecto en el menú desplegable Provide build settings from.

    3. Establece el script con el siguiente contenido:

      /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh prebuild
    Script de ejecución de pre-acción en el editor de Scheme.

    Script de ejecución de pre-acción en el editor de Scheme.

  5. Añadir nueva fase de compilación de script de ejecución al Target

    1. Navega a la pestaña Build Phases de tu target > + > New Run Script Phase

    2. Establece el script con el siguiente contenido:

      /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble

    3. Desmarca la opción Based on dependency analysis

    4. Añade lo siguiente a Input File Lists:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
    Nueva fase de compilación de script de ejecución bajo Build Phases.

    Nueva fase de compilación de script de ejecución bajo Build Phases.

  6. (Opcional) Establecer archivo LLDB Init

    El uso del archivo LLDB Init de Flutter mejora el rendimiento al realizar la depuración en dispositivos iOS 26+ físicos.

    1. Abre Product > Scheme > Edit Scheme... > Run (en la barra lateral izquierda).

    2. Establece el LLDB Init File en la siguiente ruta:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/flutter_lldbinit

      Alternativamente, si tu scheme ya tiene un archivo LLDB Init, puedes añadir el archivo LLDB de Flutter a él. La ruta al archivo LLDB Init de Flutter debe ser relativa a la ubicación del archivo LLDB Init de tu proyecto.

      command source --relative-to-command-file "../my_flutter_app/build/ios/SwiftPackages/Scripts/flutter_lldbinit"

Establecer permisos de privacidad de red local

#

En iOS 14 y posterior, habilita el servicio DNS multicast de Dart en la versión de Debug de tu aplicación iOS. Esto añade funcionalidades de depuración como hot-reload y DevTools utilizando flutter attach.

Para establecer permisos de privacidad de red local solo en la versión de Debug de tu aplicación, crea un archivo Info.plist independiente por configuración de compilación. Los proyectos de SwiftUI comienzan sin un archivo Info.plist. Si necesitas crear una lista de propiedades, puedes hacerlo a través de Xcode o de un editor de texto. Las siguientes instrucciones asumen los valores predeterminados Debug y Release. Ajusta los nombres según sea necesario en función de las configuraciones de compilación de tu aplicación.

  1. Crear una nueva lista de propiedades.

    1. Abre tu proyecto en Xcode.

    2. En el Project Navigator, haz clic en el nombre del proyecto.

    3. Desde la lista Targets en el panel del Editor, haz clic en tu aplicación.

    4. Haz clic en la pestaña Info.

    5. Expande Custom iOS Target Properties.

    6. Haz clic derecho en la lista y selecciona Add Row.

    7. Desde el menú desplegable, selecciona Bonjour Services. Esto crea una nueva lista de propiedades en el directorio del proyecto llamada Info. Esta se muestra como Info.plist en el Finder.

  2. Cambia el nombre de Info.plist a Info-Debug.plist

    1. Haz clic en el archivo Info en la lista de proyectos a la izquierda.

    2. En el panel de la derecha Identity and Type, cambia el Name de Info.plist a Info-Debug.plist.

  3. Crear una lista de propiedades de lanzamiento.

    1. En el Project Navigator, haz clic en Info-Debug.plist.

    2. Selecciona File > Duplicate.... También puedes presionar Cmd + Shift + S.

    3. En el cuadro de diálogo, establece el campo Save As: como Info-Release.plist y haz clic en Save.

  4. Añade las propiedades necesarias a la lista de propiedades de Debug.

    1. En el Project Navigator, haz clic en Info-Debug.plist.

    2. Añade el valor String _dartVmService._tcp al array Bonjour Services.

    3. (Opcional) Para establecer el texto de diálogo de permiso personalizado deseado, añade la clave Privacy - Local Network Usage Description.

      La lista de propiedades `Info-Debug` con las claves **Bonjour Services** y **Privacy - Local Network Usage Description** agregadas.

      La lista de propiedades Info-Debug con las claves Bonjour Services y Privacy - Local Network Usage Description agregadas

  5. Target para usar diferentes listas de propiedades para diferentes modos de compilación.

    1. En el Project Navigator, haz clic en tu proyecto.

    2. Haz clic en la pestaña Build Settings.

    3. Haz clic en las subpestañas All y Combined.

    4. En la casilla de búsqueda, escribe plist. Esto limita los ajustes a aquellos que incluyen listas de propiedades.

    5. Desplázate por la lista hasta que veas Packaging.

    6. Haz clic en el ajuste Info.plist File.

    7. Cambia el valor de Info.plist File de path/to/Info.plist a path/to/Info-$(CONFIGURATION).plist.

      Actualizar la configuración de compilación de `Info.plist` para usar listas de propiedades específicas del modo de compilación.

      Actualizar la configuración de compilación de Info.plist para usar listas de propiedades específicas del modo de compilación

      Esto se resuelve como la ruta Info-Debug.plist en Debug e Info-Release.plist en Release.

      La configuración de compilación **Info.plist File** actualizada que muestra las variaciones de configuración.

      La configuración de compilación de Info.plist File actualizada que muestra las variaciones de configuración

  6. Elimina la lista de propiedades de Release de las Build Phases.

    1. En el Project Navigator, haz clic en tu proyecto.

    2. Haz clic en la pestaña Build Phases.

    3. Expande Copy Bundle Resources.

    4. Si esta lista incluye Info-Release.plist, haz clic en ella y luego haz clic en el signo - (menos) debajo de ella para eliminar la lista de propiedades de la lista de recursos.

      La fase de compilación **Copy Bundle** mostrando el ajuste **Info-Release.plist**. Elimina este ajuste.

      La fase de compilación Copy Bundle mostrando el ajuste Info-Release.plist. Elimina este ajuste.

  7. La primera pantalla de Flutter que carga tu aplicación en modo Debug te solicitará permiso para acceder a la red local.

    Haz clic en OK.

    (Opcional) Para otorgar el permiso antes de que se cargue la aplicación, habilita Settings > Privacy > Local Network > Tu aplicación.

Próximos pasos

#

Ahora puedes añadir una pantalla de Flutter a tu aplicación iOS existente.

A menos que se indique lo contrario, la documentación de este sitio refleja Flutter 3.44.0. Página actualizada por última vez el 2026-06-08. Ver código fuente oreportar un problema.