This article focuses on practical Flutter-to-OpenHarmony adaptation. It covers project integration, HAP build and installation, the hdc debugging workflow, and fixes for two high-frequency issues: signature verification failures and port forwarding failures. It is designed for teams migrating existing Flutter projects to OpenHarmony. Keywords: Flutter, OpenHarmony, signature debugging.
Technical specifications at a glance
| Parameter | Description |
|---|---|
| Core languages | Dart, ETS, TypeScript, JSON5 |
| Runtime platform | OpenHarmony / HarmonyOS-compatible environment |
| Build protocol | HAP packaging, hdc device communication, bm installation |
| Core dependencies | @ohos/flutter_ohos, flutter-hvigor-plugin, Hvigor, ohpm |
| Device communication tool | hdc.exe 3.2.0b |
| Device API | const.ohos.apiversion = 22 |
| Article focus | Signature verification, port forwarding, debug connectivity |
| Star count | Not provided in the source content |
The core path for integrating Flutter with OpenHarmony is embedding the Flutter engine into an Ability container
The essence of adapting Flutter to OpenHarmony is not rewriting the business layer. Instead, you provide a Harmony-side host shell for your existing Dart code. A typical flow sends business code in lib/ into the @ohos/flutter_ohos engine, then uses Hvigor to build a hap, and finally installs it on a device through hdc and bm install.
The four most important file categories in the project are application metadata, signing configuration, module permissions, and the entry Ability. They are located in ohos/AppScope/app.json5, ohos/build-profile.json5, ohos/entry/src/main/module.json5, and ohos/entry/src/main/ets/entryability/EntryAbility.ets.
The entry Ability must explicitly start the Flutter engine and register plugins
import { FlutterAbility } from '@ohos/flutter_ohos'; // Import the Flutter Ability host
import { GeneratedPluginRegistrant } from '../generated/GeneratedPluginRegistrant';
export default class EntryAbility extends FlutterAbility {
configureFlutterEngine(flutterEngine) {
GeneratedPluginRegistrant.registerWith(flutterEngine); // Register plugin implementations
}
}This code makes the OpenHarmony entry Ability act as the Flutter container and completes plugin binding.
Hvigor must know where the Flutter project root is located
If hvigorfile.ts does not correctly connect to the Flutter project, you will eventually see missing resources, build artifacts, or plugin registration files. In particular, GeneratedPluginRegistrant.ets is typically generated during the build process. Being ignored by .gitignore does not mean anything is wrong.
Complete environment variable configuration determines whether the toolchain works
When flutter doctor -v reports that ohpm or hvigorw is missing, the root cause is usually that the system PATH cannot locate the OpenHarmony command-line tools. On Windows, you typically need to add the ohpm and hvigor executable paths from the corresponding DevEco Studio directories to the environment variables.
Verify that ohpm and hvigorw are available first
where ohpm
where hvigorw
ohpm -v
hvigorw -v
flutter doctor -vThese commands confirm that the package manager, build tool, and Flutter Harmony toolchain are available and working correctly.
After fixing the environment, you can directly run the standard debug command to trigger HAP build, installation, and launch.
flutter run -d xxxxxxThis command builds and launches the Flutter app on the target OpenHarmony device in one step.
Manual HAP installation can quickly isolate Flutter toolchain issues
If you suspect the problem is not in the Flutter layer but in signing or device permissions, skip flutter run and manually upload and install the hap with hdc. This lets you quickly determine whether the failure happens during build time or installation time.
Upload the package first and then install it to better observe device-side errors
& "C:\Users\wf\AppData\Local\OpenHarmony\Sdk\20\toolchains\hdc.exe" -t xxxxxx file send ".\build\ohos\hap\entry-default-signed.hap" "data/local/tmp/entry-default-signed.hap"
& "C:\Users\wf\AppData\Local\OpenHarmony\Sdk\20\toolchains\hdc.exe" -t xxxxxx shell bm install -p "data/local/tmp/entry-default-signed.hap"These commands push the build artifact to the device and directly invoke the system installer.
The root cause of fail to verify pkcs7 file is usually that the device does not trust the signing chain
This error is not specific to Flutter. It means the OpenHarmony device rejected the current signature while validating the HAP certificate chain, p7b, or PKCS7 metadata. In many cases, a debug certificate generated on a local machine is not accepted by a production device.
A typical error and the official direction look like this
error: failed to install bundle. code:9568257 error: fail to verify pkcs7 file.This error indicates that installation reached the package verification stage, but signature validation failed.
Some references suggest disabling strict verification through system parameters, but that only works if the device allows system parameter changes. On a production undebuggable build, this approach usually does not work.
& "C:\Users\wf\AppData\Local\OpenHarmony\Sdk\20\toolchains\hdc.exe" -t xxxxxx shell param set persist.bms.ohCert.verify true
hdc -t xxxxxx smodeThese commands attempt to modify certificate verification parameters and enter a higher-privilege mode. On non-debug systems, they usually fail.
There are only two effective ways to solve signing issues
First, switch to a debuggable device, emulator, or development board, and validate the workflow in an environment that allows parameter changes. Second, re-sign the package according to device requirements and use a trusted release certificate chain instead of the default local debug signature. The signing configuration entry is located under app.signingConfigs in ohos/build-profile.json5.
Debug connection failures usually mean port forwarding did not succeed, not that the app failed to start
When Flutter debugs on OpenHarmony, it uses hdc fport to map a local port to a listening port on the device. If the local port cannot be bound, is already in use, or stale forwarding rules exist, you may see Forward parament failed and TCP Port listen failed.
Pinning known-good ports is the most direct fix
flutter run -d xxxxxx --host-vmservice-port=51000 --dds-port=51001This command explicitly sets the vmservice and DDS ports, which avoids failures caused by default ports that cannot be bound.
If 51000/51001 is still unavailable, try a new range such as 52000/52001 or 53000/53001. In practice, this is often the fastest recovery method.
You should also inspect stale fport mappings
& "C:\Users\wf\AppData\Local\OpenHarmony\Sdk\20\toolchains\hdc.exe" fport ls
& "C:\Users\wf\AppData\Local\OpenHarmony\Sdk\20\toolchains\hdc.exe" kill -rThe first command lists current port forwarding rules. The second restarts the hdc service and clears abnormal state.
If you also need to confirm whether the device port is actually listening, run a network status query.
& "C:\Users\wf\AppData\Local\OpenHarmony\Sdk\20\toolchains\hdc.exe" -t xxxxxx shell netstat -an | Select-String -Pattern ":34297\b"This command verifies whether the target device-side port is in the LISTEN state, helping you determine whether the issue is on the device side or the host side.
During project migration, permission declarations and plugin availability are the easiest details to overlook
OpenHarmony permissions are not configured in the Flutter layer. They belong in module.json5. For example, network access requires ohos.permission.INTERNET. Without it, the app may launch successfully but all network requests can still fail.
Another high-frequency issue is Flutter plugin support. Not every Flutter plugin already has an OpenHarmony implementation. When a plugin does not work, troubleshoot in this order: first verify whether the plugin supports OpenHarmony, then check whether plugin registration was generated, and only then investigate business logic.
A quick troubleshooting checklist
1. Installation error pkcs7: Check the signing chain and device debug attributes first.
2. flutter doctor error: Add ohpm and hvigorw to PATH first.
3. Debug connection failure: Switch to a different port range first, then clear hdc fport state.
4. No network access or abnormal capabilities: Review permission declarations in module.json5.
5. Plugin failure: Confirm that the plugin provides an OpenHarmony implementation.Use this checklist to quickly classify issues into one of five areas: signing, environment, ports, permissions, or plugins.
FAQ
Q1: Why can flutter run build successfully while HAP installation still fails?
A: A successful build only proves that the local toolchain is working. Installation failures usually happen during device-side verification. The most common reason is that the HAP signature is not accepted by the device, especially on production hardware that strictly restricts debug certificates.
Q2: What is the difference between Forward parament failed and TCP Port listen failed?
A: The former is the overall result of a failed port forwarding setup. The latter more specifically points to a local port binding failure, usually caused by port conflicts, permission limits, or stale fport rules.
Q3: What should I check first when a Flutter plugin fails on OpenHarmony?
A: First confirm that the plugin has an OpenHarmony platform implementation. Then check whether GeneratedPluginRegistrant was generated during the build. Finally, verify that the entry Ability completed plugin registration.
Core summary: This article reconstructs the project integration, build-and-run workflow, and troubleshooting process for migrating Flutter to OpenHarmony. It focuses on the signature verification issue behind HAP installation failures and debug connection failures caused by hdc port forwarding, and it provides executable commands and a practical troubleshooting checklist.