Cordova自定义框架添加问题：链接错误与运行时找不到框架

Hey there! I totally get the frustration of having to manually fix Xcode configs every time you add a Cordova plugin—let’s get this sorted so everything happens automatically. Let’s break down your two issues and walk through the solutions:

First, let’s understand why your current setups aren’t working #

• When using <source-file src="src/ios/my.framework" framework="true"/>:
  The source-file tag is primarily meant for adding individual source files, and while the framework="true" flag tells Cordova to treat it as a framework, it doesn’t handle embedding the framework into your app bundle or ensuring the correct search paths are set. That’s why it’s missing at runtime.

• When using <framework src="src/ios/my.framework" custom="true" embed="true" />:
  This is closer, but link errors usually happen if the framework is static (not dynamic) and you’re forcing embedding, or if there’s a mismatch in the framework’s architecture, or if the linker can’t find the framework’s symbols properly.

Step-by-step solutions based on your framework type #

If you’re using a dynamic framework #

This is the most common case where embedding is required. Use this configuration in your plugin.xml:

<framework src="src/ios/my.framework" custom="true" embed="true" weak="false" />

• custom="true": Tells Cordova this isn’t a system framework, so it needs to handle it specially.
• embed="true": Ensures the framework is copied into your app’s bundle (critical for runtime access).
• weak="false": Set this to true only if the framework is optional (your app can run without it). For mandatory frameworks, keep it false.

Additionally, add an <xcconfig> block to ensure Xcode knows where to find the framework:

<xcconfig>
  FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../plugins/your-plugin-id/src/ios
  OTHER_LDFLAGS = -framework my
</xcconfig>

Replace your-plugin-id with your actual plugin’s ID—this makes sure the linker can locate the framework during build.

If you’re using a static framework #

Static frameworks don’t need embedding (they’re compiled directly into your app), so the embed="true" flag is causing the link error. Use this setup instead:

<source-file src="src/ios/my.framework" framework="true" />

Then add the same <xcconfig> block as above to set the search path and linker flags. This ensures the framework is included in the build and linked correctly.

For stubborn cases: Use a Cordova hook #

If the above configs still don’t work (some frameworks have weird edge cases), add an after_prepare hook to automate the Xcode project edits you’re doing manually.

1. Add this to your plugin.xml:

<hook type="after_prepare" src="scripts/ios-framework-fix.js" />

2. Create a scripts/ios-framework-fix.js file in your plugin with this code:

const xcode = require('xcode');
const fs = require('fs');
const path = require('path');

module.exports = function(context) {
  // Replace with your project name and plugin ID
  const projectName = 'YourAppName';
  const pluginId = 'your-plugin-id';
  
  const iosProjPath = path.join(context.opts.projectRoot, `platforms/ios/${projectName}.xcodeproj/project.pbxproj`);
  const frameworkPath = `../plugins/${pluginId}/src/ios/my.framework`;
  
  const proj = xcode.project(iosProjPath).parse();
  
  // Add the framework and set embed/sign options
  const fileRef = proj.addFramework(frameworkPath, { embed: true, sign: true });
  proj.addToPbxBuildFileSection(fileRef);
  proj.addToPbxFrameworksBuildPhase(fileRef);
  
  // Write the changes back to the project file
  fs.writeFileSync(iosProjPath, proj.writeSync());
};

Make sure to install the xcode npm package as a dev dependency in your plugin (npm install xcode --save-dev) so the hook can run properly.

Final checks #

• Verify that my.framework is correctly placed in your plugin’s src/ios directory.
• Ensure the framework is built for iOS (not macOS) and includes the correct architectures (arm64 for devices, x86_64 for simulators).
• After adding the plugin, run cordova prepare ios and check the Xcode project to confirm the framework is added and embedded (for dynamic frameworks) correctly.

内容的提问来源于stack exchange，提问作者Paulo