簡(jiǎn)介ZXing.Net.0.16.8.0 是面向 C# 與 Unity 開發(fā)者的開源條碼處理庫(kù)基于 Zebra Crossing 項(xiàng)目可在 .NET 框架與 Unity 引擎中實(shí)現(xiàn) QR 碼、Aztec、Code 128、EAN 等多種條碼的讀取與生成。開發(fā)者只需調(diào)用少量 API 即可為桌面應(yīng)用、移動(dòng)端或游戲加入掃碼功能例如讓玩家掃描屏幕條碼獲取游戲內(nèi)物品信息。壓縮包共 132 個(gè)文件約 18.27MB以 dll 動(dòng)態(tài)庫(kù)、pdb 調(diào)試符號(hào)、xml 文檔注釋為主另含 pri、winmd、cmd 腳本及 COPYING、THANKS 等說明文件覆蓋 net4.0、net4.6、net5.0、sl4、sl5、wp8.0、ce2.0 等多個(gè)平臺(tái)版本便于按目標(biāo)框架挑選依賴。目前已有 923 人學(xué)習(xí)下載適合需要跨平臺(tái)條碼識(shí)別能力的中高級(jí) C# 與 Unity 開發(fā)者參考可幫助快速完成庫(kù)的選型、導(dǎo)入與兼容性適配。1. 從一次掃碼翻車說起ZXing.Net 0.16.8.0 到底能解決什么去年幫一個(gè)做倉(cāng)儲(chǔ)盤點(diǎn)的團(tuán)隊(duì)看問題他們的 Unity 項(xiàng)目在 PC 編輯器里掃碼識(shí)別率接近百分之百打包到 Android 真機(jī)后同一張二維碼十次里能失敗六七次。排查了兩天最后發(fā)現(xiàn)是攝像頭采集的幀格式和識(shí)別庫(kù)之間的色彩空間沒對(duì)齊跟算法本身沒關(guān)系。那次之后我養(yǎng)成了一個(gè)習(xí)慣凡是涉及條碼識(shí)別的項(xiàng)目先把底層庫(kù)的版本、依賴和平臺(tái)差異摸清楚再談業(yè)務(wù)邏輯。ZXing.Net 0.16.8.0 就是這樣一個(gè)值得先摸清楚的底層庫(kù)——它是 ZXingZebra Crossing的 .NET 移植版本支持 QR Code、Data Matrix、Code 128、EAN-13 等主流一維和二維條碼的生成與解碼可以跑在 .NET Framework、.NET Core、.NET Standard 以及 Unity 的 C# 運(yùn)行時(shí)里。如果你正在用 Unity 做掃碼登錄、庫(kù)存管理、票務(wù)核驗(yàn)或者需要在服務(wù)端批量生成條碼圖片這個(gè)包基本是繞不開的選項(xiàng)。它適合兩類人一類是剛接觸條碼識(shí)別、想找一個(gè)能直接跑通的 C# 方案的新手另一類是已經(jīng)用過其他庫(kù)、但被平臺(tái)兼容性或識(shí)別率折騰過的熟手。接下來我會(huì)把它的核心用法、參數(shù)調(diào)優(yōu)和幾個(gè)容易翻車的地方拆開講。2. 核心解碼鏈路從圖像到文本的完整實(shí)現(xiàn)2.1 為什么選 ZXing.Net 而不是自己寫解析條碼識(shí)別看起來簡(jiǎn)單——找到黑白模塊、按規(guī)則翻譯成字符——但真正落地時(shí)會(huì)遇到一堆工程問題圖像有透視畸變?cè)趺崔k、光照不均導(dǎo)致二值化閾值失效怎么辦、多個(gè)條碼同時(shí)出現(xiàn)在畫面里怎么定位、不同碼制的糾錯(cuò)等級(jí)怎么處理。ZXing 內(nèi)部把這些都封裝成了可配置的 Pipeline包括灰度化、二值化、條碼區(qū)域檢測(cè)、網(wǎng)格采樣、糾錯(cuò)解碼幾個(gè)階段。自己從零實(shí)現(xiàn)一套能穩(wěn)定跑的保守估計(jì)要投入幾個(gè)月而且很難覆蓋所有碼制。ZXing.Net 0.16.8.0 在這個(gè)基礎(chǔ)上做了 .NET 側(cè)的適配把 Bitmap 和 Unity 的 Color32 數(shù)組之間的轉(zhuǎn)換、多線程解碼、結(jié)果回調(diào)都準(zhǔn)備好了。常見做法是直接引用它的核心庫(kù)然后在自己的采集層做幀格式轉(zhuǎn)換把圖像喂給 BarcodeReader 就行。2.2 最小可運(yùn)行示例解碼一張本地圖片先看最基礎(chǔ)的用法從一張 PNG 圖片里讀出二維碼內(nèi)容。這段代碼在 .NET Core 控制臺(tái)項(xiàng)目和 Unity 的 Editor 腳本里都能跑。using ZXing; using System.Drawing; // .NET Core 需要額外引用 System.Drawing.Common // 創(chuàng)建解碼器指定可能出現(xiàn)的碼制 var reader new BarcodeReader { // 只開啟 QR Code減少誤識(shí)別 Options new ZXing.Common.DecodingOptions { PossibleFormats new ListBarcodeFormat { BarcodeFormat.QR_CODE }, TryHarder true, // 對(duì)模糊圖像更努力地嘗試 TryInverted true // 同時(shí)嘗試反色圖像 } }; // 加載圖片并解碼 using var bitmap new Bitmap(qrcode.png); var result reader.Decode(bitmap); if (result ! null) { Console.WriteLine($格式: {result.BarcodeFormat}); Console.WriteLine($內(nèi)容: {result.Text}); // 二維碼四個(gè)角點(diǎn)可用于定位或繪制 foreach (var point in result.ResultPoints) { Console.WriteLine($角點(diǎn): {point.X}, {point.Y}); } } else { Console.WriteLine(未識(shí)別到條碼); }這段代碼的關(guān)鍵在DecodingOptions的三個(gè)參數(shù)。PossibleFormats限定碼制是最容易被忽略的優(yōu)化點(diǎn)——如果不限制解碼器會(huì)依次嘗試所有支持的格式耗時(shí)可能翻好幾倍而且容易把紋理誤判成條碼。TryHarder開啟后解碼器會(huì)在第一次失敗后嘗試更復(fù)雜的二值化策略和旋轉(zhuǎn)角度代價(jià)是耗時(shí)增加適合對(duì)識(shí)別率要求高、對(duì)延遲不敏感的場(chǎng)景。TryInverted處理白底黑碼和黑底白碼兩種情況有些工業(yè)場(chǎng)景的標(biāo)簽是反色印刷的不開這個(gè)參數(shù)就會(huì)漏掉。2.3 Unity 環(huán)境下的圖像采集與解碼適配Unity 里沒有 System.Drawing圖像數(shù)據(jù)通常是WebCamTexture或Color32[]數(shù)組。ZXing.Net 提供了Color32LuminanceSource來直接接收 Unity 的像素?cái)?shù)據(jù)省去轉(zhuǎn) Bitmap 的開銷。using UnityEngine; using ZXing; using System.Collections.Generic; public class QRScanner : MonoBehaviour { private WebCamTexture camTexture; private BarcodeReader reader; private float scanInterval 0.2f; // 每 200ms 解碼一次避免每幀都跑 private float timer; void Start() { // 初始化攝像頭 camTexture new WebCamTexture(640, 480, 30); camTexture.Play(); // 配置解碼器 reader new BarcodeReader { Options new ZXing.Common.DecodingOptions { PossibleFormats new ListBarcodeFormat { BarcodeFormat.QR_CODE }, TryHarder true } }; } void Update() { timer Time.deltaTime; if (timer scanInterval || !camTexture.isPlaying) return; timer 0; // 獲取當(dāng)前幀像素 Color32[] pixels camTexture.GetPixels32(); int width camTexture.width; int height camTexture.height; // 直接傳入 Color32 數(shù)組內(nèi)部會(huì)做灰度化 var source new Color32LuminanceSource(pixels, width, height); var result reader.Decode(source); if (result ! null) { Debug.Log($識(shí)別成功: {result.Text}); // 觸發(fā)業(yè)務(wù)邏輯比如打開鏈接、提交表單 } } void OnDestroy() { if (camTexture ! null) camTexture.Stop(); } }這里有幾個(gè)參數(shù)需要根據(jù)實(shí)際設(shè)備調(diào)整。scanInterval控制解碼頻率移動(dòng)端每幀解碼會(huì)迅速吃滿 CPU 導(dǎo)致發(fā)熱降頻200ms 一次是識(shí)別速度和功耗的折中。攝像頭分辨率 640x480 對(duì)二維碼識(shí)別通常夠用再高會(huì)增加像素拷貝和灰度化的耗時(shí)。Color32LuminanceSource內(nèi)部用的是標(biāo)準(zhǔn)灰度公式0.299R 0.587G 0.114B如果你的場(chǎng)景光照偏色嚴(yán)重可以考慮先做一次白平衡再傳入。2.4 生成條碼編碼參數(shù)與輸出格式除了解碼ZXing.Net 也能生成條碼。服務(wù)端批量出碼、Unity 里動(dòng)態(tài)渲染二維碼都用得上。using ZXing; using ZXing.QrCode; using ZXing.Common; // 配置二維碼生成參數(shù) var writer new BarcodeWriterPixelData { Format BarcodeFormat.QR_CODE, Options new QrCodeEncodingOptions { Height 256, Width 256, Margin 2, // 靜默區(qū)寬度單位是模塊數(shù) ErrorCorrection ZXing.QrCode.Internal.ErrorCorrectionLevel.H, CharacterSet UTF-8 // 支持中文內(nèi)容 } }; // 生成像素?cái)?shù)據(jù) var pixelData writer.Write(https://example.com/order/12345); // pixelData.Pixels 是 BGRA 格式的字節(jié)數(shù)組可以直接創(chuàng)建 Texture2DErrorCorrection設(shè)成 H 級(jí)別意味著二維碼有 30% 的糾錯(cuò)能力適合印刷后可能磨損或部分遮擋的場(chǎng)景代價(jià)是同樣內(nèi)容需要更多模塊碼會(huì)變密。Margin是靜默區(qū)很多生成庫(kù)默認(rèn)給 0導(dǎo)致掃碼器找不到邊界這是個(gè)高頻翻車點(diǎn)。CharacterSet不設(shè) UTF-8 的話中文內(nèi)容會(huì)亂碼這個(gè)在 0.16.x 版本里需要顯式指定。3. 參數(shù)調(diào)優(yōu)與性能邊界讓識(shí)別率從 70% 到 95%3.1 二值化策略的選擇邏輯ZXing 內(nèi)部默認(rèn)用 HybridBinarizer它把圖像分成 8x8 的塊每塊單獨(dú)計(jì)算閾值適合光照不均勻的場(chǎng)景。但在某些情況下GlobalHistogramBinarizer 反而更穩(wěn)——比如圖像整體對(duì)比度高、沒有明顯陰影的時(shí)候。切換方式是在 DecodingOptions 里設(shè)置var options new ZXing.Common.DecodingOptions { PossibleFormats new ListBarcodeFormat { BarcodeFormat.QR_CODE }, TryHarder true }; // 通過 BarcodeReader 的 Binarizer 屬性切換 reader.Binarizer new ZXing.Common.GlobalHistogramBinarizer(source);我一般會(huì)先跑一遍默認(rèn)的 Hybrid如果識(shí)別率不理想再換 Global 對(duì)比。工業(yè)視覺場(chǎng)景里如果打光可控Global 往往更快更準(zhǔn)移動(dòng)端手持掃描Hybrid 適應(yīng)性更好。3.2 圖像預(yù)處理裁剪、縮放與銳化ZXing 對(duì)輸入圖像的尺寸有隱式要求。如果圖像太大解碼耗時(shí)會(huì)線性增長(zhǎng)太小則條碼模塊模糊采樣失敗。經(jīng)驗(yàn)值是二維碼在圖像中占據(jù)的面積不低于 10%每個(gè)模塊至少 3 個(gè)像素。在 Unity 里可以在傳入前做一次中心裁剪// 假設(shè)原始圖像 1280x720裁剪中心 640x480 區(qū)域 int cropW 640, cropH 480; int startX (width - cropW) / 2; int startY (height - cropH) / 2; Color32[] cropped new Color32[cropW * cropH]; for (int y 0; y cropH; y) { for (int x 0; x cropW; x) { cropped[y * cropW x] pixels[(startY y) * width (startX x)]; } } var source new Color32LuminanceSource(cropped, cropW, cropH);裁剪減少了解碼器需要掃描的像素量同時(shí)把條碼區(qū)域放大到畫面中心對(duì)焦也更準(zhǔn)。如果條碼本身很小可以先做一次雙線性插值放大再傳入但放大倍數(shù)不要超過 2 倍否則插值帶來的模糊反而會(huì)降低識(shí)別率。3.3 多碼制共存時(shí)的優(yōu)先級(jí)與沖突一個(gè)畫面里同時(shí)出現(xiàn) QR Code 和 Code 128 時(shí)如果 PossibleFormats 里兩個(gè)都開著解碼器會(huì)按內(nèi)部順序嘗試先命中的返回。這可能導(dǎo)致你想讀 QR 卻讀到了旁邊的條形碼。解決辦法有兩種一是根據(jù)業(yè)務(wù)場(chǎng)景只開需要的格式二是用DecodeMultiple方法拿到所有結(jié)果再按格式篩選。var results reader.DecodeMultiple(source); foreach (var r in results) { if (r.BarcodeFormat BarcodeFormat.QR_CODE) { // 處理二維碼 } }DecodeMultiple在 0.16.8.0 里已經(jīng)支持但性能比單碼解碼低不少只在確實(shí)需要多碼同讀時(shí)用。3.4 線程模型別在主線程里跑解碼Unity 的 Update 里直接調(diào) Decode 會(huì)阻塞渲染。移動(dòng)端上一幀解碼耗時(shí)可能到 50-100ms直接導(dǎo)致掉幀。常見做法是丟到 ThreadPool 或 Task 里跑主線程只負(fù)責(zé)采集和渲染結(jié)果。private bool isDecoding false; void Update() { if (isDecoding || timer scanInterval) return; timer 0; isDecoding true; Color32[] pixels camTexture.GetPixels32(); int w camTexture.width, h camTexture.height; System.Threading.Tasks.Task.Run(() { var source new Color32LuminanceSource(pixels, w, h); var result reader.Decode(source); // 回到主線程更新 UI UnityMainThreadDispatcher.Enqueue(() { if (result ! null) Debug.Log(result.Text); isDecoding false; }); }); }注意Color32LuminanceSource構(gòu)造時(shí)不會(huì)拷貝數(shù)組如果后臺(tái)線程解碼的同時(shí)主線程在寫 pixels會(huì)有數(shù)據(jù)競(jìng)爭(zhēng)。穩(wěn)妥的做法是在 Task 里先做一次數(shù)組拷貝或者用雙緩沖交替采集。4. 避坑與排查那些文檔里不會(huì)寫的翻車現(xiàn)場(chǎng)4.1 現(xiàn)象PC 上正常打包到移動(dòng)端就識(shí)別失敗原因Unity 的 WebCamTexture 在不同平臺(tái)上返回的像素格式可能不同。PC 上通常是 RGB24Android 上可能是 YV12 或 NV21直接 GetPixels32 拿到的數(shù)據(jù)在部分設(shè)備上顏色通道順序是反的導(dǎo)致灰度化后黑白顛倒。解決在 Start 里檢查camTexture.graphicsFormat如果不是 RGB24先用WebCamTexture.GetPixels32拿到數(shù)據(jù)后手動(dòng)做一次通道交換。或者更穩(wěn)妥的做法是先用camTexture.GetPixels32()渲染到 RenderTexture再?gòu)?RenderTexture 讀取標(biāo)準(zhǔn) RGB 數(shù)據(jù)。4.2 現(xiàn)象識(shí)別率突然下降之前能掃的碼現(xiàn)在掃不出來原因ZXing.Net 0.16.8.0 默認(rèn)的AutoRotate是關(guān)閉的。如果攝像頭畫面旋轉(zhuǎn)了 90 度比如手機(jī)橫屏拿但應(yīng)用鎖豎屏條碼在圖像里是側(cè)著的解碼器找不到定位圖案。解決在 DecodingOptions 里設(shè)AutoRotate true或者自己在傳入前把圖像旋轉(zhuǎn)到正確方向。AutoRotate 會(huì)嘗試 0/90/180/270 四個(gè)角度耗時(shí)增加約 30%但能覆蓋絕大多數(shù)方向問題。4.3 現(xiàn)象生成的中文二維碼掃出來是亂碼原因QrCodeEncodingOptions.CharacterSet默認(rèn)不是 UTF-8在 0.16.x 里如果不顯式設(shè)置中文內(nèi)容會(huì)按 ISO-8859-1 編碼寫入掃碼端按 UTF-8 解析就亂了。解決生成時(shí)強(qiáng)制指定CharacterSet UTF-8。另外注意部分老款掃碼 App 對(duì) UTF-8 的支持也不完善如果目標(biāo)用戶環(huán)境不可控可以考慮把中文內(nèi)容先做 Base64 編碼再寫入掃碼后自行解碼。4.4 現(xiàn)象TryHarder 開了之后 CPU 占用飆升手機(jī)發(fā)燙原因TryHarder 會(huì)在首次解碼失敗后嘗試多種二值化策略和旋轉(zhuǎn)角度每次嘗試都是一次完整的圖像掃描。如果畫面里根本沒有條碼每幀都在做無用功。解決加一個(gè)前置判斷——先用簡(jiǎn)單的邊緣檢測(cè)或方差計(jì)算判斷畫面里是否有足夠的黑白對(duì)比區(qū)域沒有就直接跳過解碼。或者降低解碼頻率從每 200ms 一次改成每 500ms 一次配合 UI 上的掃描框引導(dǎo)用戶對(duì)準(zhǔn)。4.5 現(xiàn)象NuGet 安裝后編譯報(bào)錯(cuò)找不到 ZXing.Common.DecodingOptions原因ZXing.Net 0.16.8.0 的 NuGet 包分了多個(gè)目標(biāo)框架版本Unity 項(xiàng)目如果用的是 .NET Standard 2.0 兼容模式可能引用到了不包含完整 API 的程序集。解決確認(rèn) Unity 的 Api Compatibility Level 設(shè)為 .NET Standard 2.0 或 .NET 4.x然后在 NuGet 里安裝ZXing.Net主包不要只裝ZXing.Net.Bindings之類的子包。如果用的是 Unity Package Manager需要手動(dòng)把 dll 放到 Plugins 目錄下并確保平臺(tái)設(shè)置里勾選了對(duì)應(yīng)的 CPU 架構(gòu)。5. 進(jìn)階技巧用自定義 LuminanceSource 接管灰度化ZXing 默認(rèn)的灰度化公式對(duì)大多數(shù)場(chǎng)景夠用但在紅外攝像頭、低照度或高對(duì)比度工業(yè)光源下標(biāo)準(zhǔn)公式可能把條碼區(qū)域和背景壓成同一灰度。這時(shí)候可以繼承LuminanceSource自己實(shí)現(xiàn)灰度映射。using ZXing; public class CustomLuminanceSource : LuminanceSource { private byte[] luminances; public CustomLuminanceSource(Color32[] pixels, int width, int height) : base(width, height) { luminances new byte[width * height]; for (int i 0; i pixels.Length; i) { // 自定義權(quán)重增強(qiáng)綠色通道適合某些工業(yè)相機(jī) int gray (pixels[i].r * 2 pixels[i].g * 5 pixels[i].b * 1) / 8; luminances[i] (byte)Mathf.Clamp(gray, 0, 255); } } public override byte[] GetRow(int y, byte[] row) { int offset y * Width; if (row null || row.Length Width) row new byte[Width]; for (int x 0; x Width; x) row[x] luminances[offset x]; return row; } public override byte[] Matrix luminances; }這個(gè)自定義 Source 把綠色通道權(quán)重提高到 5/8因?yàn)槎鄶?shù)圖像傳感器對(duì)綠光最敏感信噪比最高。在低照度環(huán)境下這樣加權(quán)后條碼邊緣的梯度更明顯二值化時(shí)更容易分離出黑白模塊。代價(jià)是紅色和藍(lán)色信息被壓縮如果條碼是紅色印刷在白色背景上反而可能識(shí)別不了——所以這個(gè)方案適合黑白或深色碼不適合彩色碼。另一個(gè)進(jìn)階用法是結(jié)合BarcodeReader.ResultPointCallback做實(shí)時(shí)定位反饋。在解碼過程中ZXing 會(huì)回調(diào)找到的定位點(diǎn)坐標(biāo)可以用這些點(diǎn)在 UI 上畫掃描框讓用戶知道有沒有對(duì)準(zhǔn)。reader.Options.ResultPointCallback new ResultPointCallback((point) { // point 是解碼過程中找到的定位點(diǎn) Debug.Log($定位點(diǎn): {point.X}, {point.Y}); });這個(gè)回調(diào)在每次嘗試解碼時(shí)都會(huì)觸發(fā)可以用來做掃描引導(dǎo)動(dòng)畫。注意回調(diào)是在解碼線程里執(zhí)行的更新 UI 需要切回主線程。從那以后我每次集成條碼庫(kù)都會(huì)先寫一個(gè)最小測(cè)試場(chǎng)景固定一張標(biāo)準(zhǔn)測(cè)試圖跑通解碼再逐步加攝像頭采集、多線程、平臺(tái)適配。這樣出問題時(shí)能快速定位是庫(kù)的問題還是采集層的問題。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取