我叫卡里姆，是布基納法索首都瓦加杜古的一名口腔頜面外科醫生。從醫學院時代起，我就沉迷于寫代碼，靠自學一路摸索過來。最近幾個月，我利用晚間和周末的碎片時間，獨自開發并上線了Readium，一款能在閱讀過程中和Claude實時對話的AI應用。你讀什么語言，它就用什么語言和你聊。

大部分“我發布了一個AI應用”的技術復盤，都只給你看光鮮的那一面：克隆個初始模板、接入個大語言模型、往Vercel上一扔就成了。但我在這一路上撞上的技術壁壘，全都不在這些現成方案里，它們藏在各種程序庫之間沒人注明的縫隙中。下面就是其中五個讓我頭疼不已的坑，以及回頭看看我想對幾周前的自己說點什么。

第一個坑，是流式傳輸。我原本以為只要OpenRouter那邊返回了數據流，剩下的事都是現成的。理論上確實如此，但前提是服務端處理器、反向代理和瀏覽器代碼不會在數據傳輸的任何一個環節悄悄加上緩沖。這條鏈路至少有三個地方可能暗中終結你的流式傳輸：大模型接口本身沒問題；你的Node服務端處理器只要不是把數據塊原樣轉發，而是先緩存起來，就會出問題；更致命的是反向代理或者內容分發網絡，它們默認情況下往往會把整個響應體緩存下來。表現癥狀完全一樣：界面上看著就像大模型響應特別慢。實際上根本不是模型的鍋，從OpenRouter到瀏覽器的某個中間環節，硬是把字節暫時扣住了，等連接關閉后才一股腦全拋出來。

回頭想想，我想跟當時的自己說：流式傳輸不是大模型自帶的能力，它是貫穿整條請求鏈路的一種特性。如果你在終端里用curl -N測試自己的源服務器時，沒法看到一個個字符逐次出現，那你所謂的“流式傳輸”就是在自欺欺人。從處理程序那里就要把Cache-Control: no-transform和X-Accel-Buffering: no這兩個頭部信息加上去，把每層前端代理的響應緩沖功能統統關掉。在信任界面之前，先用curl -N驗證一遍。

第二個坑藏在網絡請求里。我在應用里加了一條代理路由，用來從外部接口拉數據。本地環境跑得好好的，預發布環境也沒問題，一部署到生產環境就出狀況：這條路由會沉默整整六十秒左右，然后超時。沒有任何錯誤提示，日志里也翻不到線索。我花了兩天時間瘋狂檢查自己的代碼。兩天。問題最終鎖定在undici身上，這是Node內置的fetch實現機制。當遠端主機的域名解析同時返回IPv6和IPv4記錄時，undici會優先選擇IPv6，建立傳輸控制協議連接，然后就在那兒干等。要是容器和那個IPv6地址之間的路由不通——這在虛擬專用服務器網絡里是家常便飯——它連個超時機制都沒有，就死等。

解決辦法是繞過fetch，改用更底層的node:https，并把地址族參數強制設為4，只走IPv4。我想告訴過去的自己：當生產環境里的網絡調用無聲掛起、本地卻一切正常時，在懷疑代碼之前，先查IPv6的毛病。從Node 18把undici設為默認起，這已經是橫跨整個JavaScript開發生態的一個實實在在卻又鮮有文檔記錄的生產環境問題了。

第三個坑是平臺狀態和實際功能之間的落差。我有兩款產品在平臺上明明顯示為“已發布”，用戶打開后看到的卻是空白內容。排查下來發現，發布流程里有一個關鍵步驟沒有觸發內容構建，系統只是把狀態字段改成了已發布，靜態文件壓根沒生成。最終我不得不手動觸發重新構建流程，才把這個問題徹底解決。這類問題特別隱蔽，因為平臺面板上的狀態指示一切正常，只有真正去使用才會發現功能完全不可用。

第四個坑來自多語言支持。Readium主打的就是用任何語言討論書籍內容，但不同語言的字符集和排版規則存在巨大差異。阿拉伯語從右向左的閱讀方向、東亞語言的換行規則、某些文字需要額外字體支持，這些細節處理不好，閱讀體驗就會大打折扣。我最初低估了字體回退機制的復雜度，以為瀏覽器能自動處理，結果在特定語言環境下出現了字符重疊和排版錯亂的問題。必須針對每種文字系統做單獨的樣式調整和測試。

第五個坑是成本控制。大模型接口的調用成本遠比我預估的要高，特別是在處理長文本語境時。用戶和Claude討論一本書的完整章節，上下文窗口會迅速膨脹，每次對話的令牌消耗量比測試階段高出好幾倍。我不得不重新設計對話摘要和上下文裁剪策略，在保持對話連貫性的前提下，把每次請求攜帶的歷史信息壓縮到最低限度。這套方案需要在用戶能夠回憶更早對話內容的體驗和成本的可持續性之間不斷做權衡和調整。

這五個坑教會我一個關鍵認知：把AI應用真正推向生產環境，遠不止是接入一個大模型接口那么簡單。真正讓人撞墻的地方，全都在那些數據流轉的縫隙、網絡協議棧的暗角、以及平臺抽象層之下沒有被清楚標明文檔的地方。這些問題不挑開發者的資歷，只看你是不是完整走完了從寫到部署、再到用戶實際使用的整條鏈路。