buildIOSPlugin

UniApp iOS 插件开发构建函数。

这是 buildIOSApp 的简化版本，专门用于 iOS 插件开发场景。

特点

与完整的应用打包相比，插件开发构建有以下特点：

1. 默认使用 Debug 配置 - 适合开发调试
2. 始终启用自定义基座模式 - 插件开发必需
3. 只构建到 archive - 不导出 IPA，构建速度更快
4. 专门针对 HBuilder-uniPluginDemo 项目结构优化

函数签名

function buildIOSPlugin(
  options: UniAppIOSPluginBuildOptions,
  deps: BuildIOSAppDeps
): Promise<UniAppIOSBuildResult>

参数

options: UniAppIOSPluginBuildOptions

插件构建选项对象。

属性	类型	必需	说明
uniappProjectPath	string	是	UniApp 项目路径
projectPath	string	是	iOS 插件项目路径（如 HBuilder-uniPluginDemo/HBuilder-Hello）
bundleId	string	否	iOS Bundle Identifier
appkey	string	否	UniApp 应用密钥
uniappBuildOutputPath	string	否	UniApp 编译结果路径（如果提供则跳过构建步骤）
configuration	'Debug' | 'Release'	否	构建配置，默认为 'Debug'
scheme	string	否	Xcode Scheme 名称
clean	boolean	否	是否清理构建，默认为 false
outputPath	string	否	输出路径
signing	IOSSigningOptions	否	签名配置
nativePlugins	UniAppNativePluginIOSOptions[]	否	原生插件配置列表

deps: BuildIOSAppDeps

依赖函数对象，包含文件系统、路径、子进程等操作函数。

返回值

返回 Promise<UniAppIOSBuildResult>：

interface UniAppIOSBuildResult {
  success: boolean      // 是否成功
  outputPath?: string   // 输出的 archive 文件路径
  error?: string        // 错误信息（如果失败）
  logs: string[]        // 构建日志
}

使用示例

基础用法

import * as fs from 'fs'
import * as path from 'path'
import * as child_process from 'child_process'
import JSON5 from 'json5'
import { DOMParser, XMLSerializer } from '@xmldom/xmldom'
import * as xpath from 'xpath'
import { buildIOSPlugin } from 'zcw-shared/functions/uniapp/app-plus/buildIOSApp'
import type { UniAppIOSPluginBuildOptions } from 'zcw-shared/types/uniapp-ios-build'
import type { BuildIOSAppDeps } from 'zcw-shared/functions/uniapp/app-plus/buildIOSApp'

async function main() {
  const options: UniAppIOSPluginBuildOptions = {
    uniappProjectPath: '/path/to/uniapp/project',
    projectPath: '/path/to/HBuilder-uniPluginDemo/HBuilder-Hello',
    bundleId: 'com.example.app',
    appkey: 'your-appkey-here',
    configuration: 'Debug',
    clean: true,
    outputPath: '/path/to/output',
    signing: {
      teamId: 'XXXXXXXXXX' // 你的开发团队 ID
    }
  }

  const deps: BuildIOSAppDeps = {
    existsSync: fs.existsSync,
    readFileSync: fs.readFileSync,
    writeFileSync: fs.writeFileSync as any,
    copyFileSync: fs.copyFileSync,
    mkdirSync: fs.mkdirSync,
    readdirSync: fs.readdirSync,
    statSync: fs.statSync,
    cp: fs.promises.cp,
    join: path.join,
    dirname: path.dirname,
    basename: path.basename,
    exec: child_process.exec,
    platform: process.platform,
    parse: JSON5.parse,
    xmlParser: DOMParser,
    xmlSerializer: XMLSerializer,
    xpath: xpath,
    setTimeout
  }

  const result = await buildIOSPlugin(options, deps)

  if (result.success) {
    console.log('✅ 构建成功！')
    console.log(`Archive 文件: ${result.outputPath}`)
  } else {
    console.error('❌ 构建失败:', result.error)
  }

  // 打印所有日志
  result.logs.forEach(log => console.log(log))
}

main()

集成原生插件

const options: UniAppIOSPluginBuildOptions = {
  uniappProjectPath: '/path/to/uniapp/project',
  projectPath: '/path/to/HBuilder-uniPluginDemo/HBuilder-Hello',
  bundleId: 'com.example.app',
  appkey: 'your-appkey',
  signing: {
    teamId: 'XXXXXXXXXX'
  },
  // 配置原生插件
  nativePlugins: [
    {
      pluginPath: '/path/to/plugin.zip',
      parameters: {
        appid: 'your-plugin-appid',
        appkey: 'your-plugin-appkey'
      }
    }
  ]
}

const result = await buildIOSPlugin(options, deps)

使用预编译的 UniApp 资源

如果你已经编译好了 UniApp 项目，可以直接使用编译结果，跳过 UniApp 构建步骤：

const options: UniAppIOSPluginBuildOptions = {
  uniappProjectPath: '/path/to/uniapp/project',
  projectPath: '/path/to/HBuilder-uniPluginDemo/HBuilder-Hello',
  // 使用预编译的资源
  uniappBuildOutputPath: '/path/to/uniapp/project/dist/build/app',
  bundleId: 'com.example.app',
  signing: {
    teamId: 'XXXXXXXXXX'
  }
}

const result = await buildIOSPlugin(options, deps)

项目结构要求

iOS 插件开发项目通常使用 HBuilder-uniPluginDemo 模板，其目录结构如下：

HBuilder-uniPluginDemo/
├── HBuilder-Hello/              # 实际的 iOS 项目（这个是 projectPath）
│   ├── HBuilder.xcodeproj       # Xcode 项目文件
│   ├── HBuilder/
│   │   ├── HBuilder-Info.plist
│   │   ├── Pandora/
│   │   │   └── apps/            # UniApp 资源目录
│   │   └── control.xml          # 控制文件
│   └── ...
└── ...

重要提示： projectPath 应该指向 HBuilder-Hello 目录，而不是 HBuilder-uniPluginDemo 根目录。

构建流程

buildIOSPlugin 函数会执行以下步骤：

1. 解析 manifest.json - 读取 UniApp 项目配置
2. 同步版本配置 - 更新 project.pbxproj 中的版本号
3. 修改 Info.plist - 配置 Bundle ID、AppKey 等信息
4. 配置自定义基座 - 在 control.xml 中添加 debug 和 syncDebug 属性
5. 编译 UniApp 项目 - 构建 UniApp 资源（如果没有提供预编译资源）
6. 复制资源文件 - 将 UniApp 资源复制到 iOS 项目的 Pandora/apps 目录
7. 集成原生插件 - 如果配置了原生插件，则集成到项目中
8. 编译 iOS 项目 - 使用 xcodebuild 编译到 archive

与 buildIOSApp 的区别

特性	buildIOSPlugin	buildIOSApp
默认配置	Debug	Release
自定义基座	始终启用	可选
输出格式	.xcarchive	.ipa
构建速度	更快	较慢
适用场景	插件开发调试	正式发布

注意事项

1. 签名配置 - 必须在 Xcode 中手动配置签名信息（Signing & Capabilities -> Team）
2. 开发团队 ID - 建议在 options.signing.teamId 中提供，但最终以 Xcode 配置为准
3. 插件开发 - 构建完成后，可以直接在 Xcode 中运行项目进行插件调试
4. IPA 导出 - 如果需要导出 IPA 文件，请使用 buildIOSApp 函数

相关文档

• buildIOSApp - 完整的 iOS 应用打包函数（位于 src/functions/uniapp/app-plus/buildIOSApp.ts）
• integrateNativePluginIOS - iOS 原生插件集成函数（位于 src/functions/ios/integrateNativePlugin.ts）

许可证

MIT