Shopify Functions üç farklı hata ayıklama alanı sunar: app dev'den akan terminal günlükleri, .shopify/logs/'taki yapılandırılmış JSON dosyaları ve Dev Dashboard'daki fonksiyon çalıştırma günlükleri. Geliştirme sürecinin hangi aşamasında hangi alanı kullanacağınızı bilmek, hata ayıklama zamanını saatlerden dakikalara indirir. app function replay komutu, gerçek bir üretim yürütmesini yerel ortamda, canlı kodunuza karşı, satıcının mağazasını etkilemeden yeniden çalıştırarak döngüyü tamamlar.
Ana çıkarımlar
shopify app devfonksiyon günlüklerini terminalinize akar ve her yürütme için JSON dosyalarını.shopify/logs/'a yazar.app function replay --log <altı-karakter-id>yakalanmış bir girişi yerel ortamda yeniden yürütür, böylece Shopify'de fonksiyonu yeniden tetiklemeden yineleyebilirsiniz.- Dev Dashboard çalıştırma günlüğü görünürlüğü uygulamanızın erişim kapsamları tarafından kontrol edilir, manuel satıcı paylaşması tarafından değil (13 Mayıs 2026 tarihinde değiştirildi).
- Fonksiyon günlükleri Dev Dashboard'da 1 kB'da kesilir; günlük ifadelerinizi buna göre tasarlayın.
- Talimatlı bütçe yürütme başına 11 milyon Wasm talimatıdır (200'e kadar satır öğesi içeren sepetler için), duvar saati zamanı değil. Dev Dashboard, yürütme başına talimat sayısını gösterir.
Üç hata ayıklama alanı ve her birini ne zaman kullanacağınız
En içten (yerel) ile en dışa (üretim) doğru hareket eden üç katmanlı bir zihinsel harita tutuyorum:
| Alan | Ne zaman kullanılır | Ana sınırlama |
|---|---|---|
app dev terminali + .shopify/logs/ | Bir geliştirme mağazasına karşı etkin geliştirme | Yalnızca tarayıcı fonksiyonu tetiklediğinde ateşlenir; keyfi girişleri yeniden oynatamaz |
app function run --input fixture.json | Bilinen veya taklit edilmiş bir girişe karşı birim seviyesi test | Giriş el ile oluşturulmalı veya bir günlükten kopyalanmalıdır; canlı bir oturuma bağlı değildir |
app function replay --log <id> | Gerçek bir yürütmeyi (geliştirme veya üretim girişi) yerel ortamda yeniden oluşturma | Yakalanmış bir günlük dosyası gerektirir; üretim çalıştırmaları Dev Dashboard dışa aktarma gerektirir |
| Dev Dashboard fonksiyon çalıştırma günlükleri | Dağıtım sonrası hata ayıklama, satıcı tarafından bildirilen arızalar | Kapsam ile sınırlıdır (aşağıya bakın); günlükler 1 kB'da kesilir |
Uygulamada yukarıdan aşağıya hareket ederim: armatürlerle yerel ortamda hızlı şekilde oluştur, sonra fonksiyon bir geliştirme mağazasına bağlandıktan sonra yeniden oynatmaya geç, sonra üretim ortamına kaçan herhangi bir şey için Dev Dashboard'a in.
app dev: diske gerçekte ne yazılır
shopify app dev çalıştırdığınızda, CLI yürütme günlüklerini terminalinize akar ve geliştirme mağazanızda ateşlenen her fonksiyon yürütmesi için .shopify/logs/'a ayrı bir JSON dosyası yazar. Her dosya <zaman-damgası>_<ad-alanı>_<işlem>_<id>.json adlandırılır ve tam girişi, çıkışı, talimat sayısını ve fonksiyonunuzun yaydığı STDERR/günlük çıkışını içerir.
Altı karakterli <id> soneki, app function replay'nin günlük dosyası tanımlayıcısı dediği şeydir. Bu tanımlayıcı ayrıca app dev terminal çıkışında her yürütmenin yanında yazdırılır. Kopyalayın ve bu tam yürütmeye sonsuza kadar sabit bir tutamağınız olur.
Uygulamanızda birden fazla Function uzantısı varsa, akışı filtreleyebilirsiniz. İkinci bir terminalde:
shopify app logs --source extensions.my-discount-function
Uzantılarınız için tam tutamak adlarını almak üzere önce shopify app logs sources çalıştırın.
CLI 5.0 notu: Shopify CLI 5.0, bağımsız app logs ve app logs sources komutlarını kaldırdı. Geçiş kılavuzu, Function günlükleri için app dev çıkışını kullanmanızı söyler. CLI 4.x üzerindeyseniz bu komutlar hala çalışır; her iki yolu varsaymadan önce shopify version kontrol edin.
app function replay: en hızlı geri bildirim döngüsü
app function replay önceden günlüğe kaydedilmiş bir yürütmeden gelen girişi kullanarak geçerli dizindeki derlenmiş Wasm ikilisini yeniden yürütür. Dosya değişikliklerini izler ve otomatik olarak yeniden çalıştırır ve tarayıcı açmaya gerek kalmadan sıkı bir düzenleme-derleme-test döngüsü sağlar.
# Belirli bir günlük kimliğini kullanarak yeniden oynat (app dev çıkışından kopyalayın)
shopify app function replay --log a3f9c1
# Kimliğiniz yoksa, son yürütmelerden etkileşimli olarak seçin
shopify app function replay
Ayrıca bir --json bayrağı da vardır (yakın zamanda bir CLI PR'sinde eklendi) bu yapılandırılmış JSONL çıkışını akar, yürütme sonucunu jq veya bir test çerçevesine yöneltmek istiyorsanız kullanışlıdır:
shopify app function replay --log a3f9c1 --json --no-input | jq '.result.instructions'
Yeniden oynatma çıkışı instructions, memory_usage, input, output ve success içerir. 11 milyon talimat bütçesine yaklaştığınızda izlemesi gereken instructions alanıdır.
Yeniden oynatma girdileri nereden gelir?
Dört yerden app function replay (ve app function run) besleyebilirsiniz:
app dev'den günlük dosyaları (.shopify/logs/*.json)- CLI 4.x üzerinde
app logsçıkışı - Dev Dashboard'dan kopyalanan fonksiyon çalıştırma günlükleri
- Giriş sorgusu şemanızla eşleşen el ile oluşturulmuş bir taklit JSON
Seçenek 3 üretim hataları için en değerlidir: hatalı yürütmeye Shopify'nin gönderdiği tam girişi dışa aktarır, yerel ortama bırakır ve yeniden oynatırsınız. Satıcının sepetinin neye benzediğini tahmin etmek gerekmez.
Dev Dashboard çalıştırma günlükleri ve kapsam geçidi (Mayıs 2026 değişikliği)
13 Mayıs 2026'dan önce, bir üretim mağazası için çalıştırma günlüğü ayrıntılarını almak, satıcının günlüğü İndirimler sekmesinden el ile paylaşmasını gerektiriyordu. Bu zorluk ortadan kalktı. Bu değişiklik güncellemesinden bu yana, Dev Dashboard'daki fonksiyon çalıştırma günlüğü ayrıntıları, uygulama fonksiyonun giriş sorgusu tarafından gerektirilen erişim kapsamlarını tuttuğunda uygulamanıza otomatik olarak görünür.
Mekanizm basittir: Shopify, giriş sorgunuzun okuduğu alanlardan gerekli kapsamları türetir. Sorgunuz customer.email'e dokunuyorsa, uygulamanız read_customers'a ihtiyaç duyar. cart.lines[].product.metafields'e dokunuyorsa, read_products'a ihtiyaç duyar. Herhangi bir kapsam kaçırırsanız Dev Dashboard çalıştırma meta verilerini (zaman damgası, mağaza, başarı/başarısızlık) gösterir ancak giriş ve çıkış yükünü tamamen gizler.
Günlükler boş olduğunda pratik kontrol listesi:
- Fonksiyonunuzun
input.graphql'i açın (veya.graphqlgiriş sorgusu dosyası). - Sorgunun okuduğu her alanı listeleyin.
- Her alanı Shopify erişim kapsamları başvurusuna karşı çapraz referans alın.
- Eksik kapsamları
shopify.app.toml'a ekleyin. - Yalnızca hata ayıklama sırasında gereken kapsamlar için (normal uygulama işlemi değil), bunları isteğe bağlı kapsamlar olarak bildirin. Satıcılar uygulamayı yeniden yüklemeden isteğe bağlı kapsamları verebilir veya iptal edebilir.
Bir hata: müşteri veri alanları (e-posta, adresler, sipariş geçmişi) korunan müşteri veri kapsamları altında düşer, bu da Shopify'den ayrı bir onay gerektirir. Sonraki üretim hata ayıklama oturumundan önce bu inceleme zamanını planlayın.
1 kB kesinti hayatta kalan günlük ifadeleri yazma
Dev Dashboard yürütme başına 1 kB'dan sonra fonksiyon günlüklerini keser. Bu yaklaşık 1.000 karakterdir. Bu sınırda, bir ayrıntılı JSON.stringify(input) çağrısı, faydalı bir şey görmeden tüm bütçenizi yakıp tüketir.
JavaScript'te:
// Kötü: tüm 1 kB'ı tek bir nesneye yakıyor
console.error(JSON.stringify(input));
// Daha iyi: yalnızca koşullu mantığınızın dallanmasını yaptığı değerleri günlüğe kaydedin
console.error(`subtotal=${input.cart.cost.subtotalAmount.amount} lines=${input.cart.lines.length} tag=${input.cart.buyerIdentity?.customer?.tags?.join(',')}`);
Rust'ta, eprintln! yerine Shopify günlükleme API'sine yazın (shopify_function::logging::log). Her ikisi de Dev Dashboard'daki "Logs" altında STDERR bölümünde bitmelidir, ancak Shopify makrosu daha idiyomatik bir yoldur ve değişme olasılığı daha düşüktür.
Günlük ifadelerinizi hata ayıklamaya çalıştığınız belirli soruyu cevaplamak için tasarlayın: fonksiyon hangi dalı aldı, ana giriş değeri ne idi, çıkış işlemleri dizisi ne içeriyordu? Üç hedefli satır her zaman JSON duvarını yenebilir.
Sorun olmadan önce talimat sayısını okuma
Dev Dashboard'daki her fonksiyon çalıştırma günlüğü ve her app function replay JSON çıkışı, o yürütme için talimat sayısını içerir. Sabit tavan, 200 satır öğeye kadar sepetler için 11 milyon Wasm talimatıdır ve bütçe bu eşiğin üzerinde orantılı olarak ölçeklenmiştir.
10.000+ SKU'lu bir kataloğa sahip her fonksiyona uyguladığım iki kural:
- Uyarı eşiği: Herhangi bir gözlemlenen çalıştırmada talimat sayısı yaklaşık 8,8 milyon (bütçenin yüzde 80'i) aşarsa, fonksiyon büyük bir sepet siparişinde risk altındadır. Dev Dashboard günlüklerine bir izleme kontrolü ekleyin.
- Dil takas: Shopify'nin kendi dokümanları, JavaScript fonksiyonlarının aynı mantık için eşdeğer Rust fonksiyonlarından talimat bütçesinden yaklaşık 10 kat daha hızlı geçtiğini belirtir. Aynı miktar sınırı doğrulaması için Rust yaklaşık 19.000 talimat kullanır, basit bir örnekte JavaScript'te kabaca 183.000 kullanır. Ölçekte, bu oran artar. Büyük sepetlerle bir JavaScript fonksiyonunda talimat sayısı kayması görüyorsanız,
app function replay --jsonaracılığıyla derlemeyi profilleyin ve yeniden yazmaya karar vermeden önce birkaç sepet boyutu genelindeinstructionsalanını inceleyin.
app function build komutu, fonksiyonunuzu Wasm'ye derler ve onu dağıtmaz. Çalıştırın, sonra app function replay derlenmiş ikilisine karşı app function run --input fixture.json çalıştırıp talimat sayısını tamamen çevrimdışı bir döngüde alın, app dev hatta resme girmeden önce.
Yaygın arıza desenleri ve önce ne kontrol etmeliyiz
- Fonksiyon çalıştı, çıkış boş, hata günlüğe kaydedilmedi: Giriş sorgunuzun koşullu mantığınızın okuduğu alanları döndürüp döndürmediğini kontrol edin. Sorgudan eksik bir alan çalışma zamanında null döndürür; fonksiyon sessizce daldan çıkar ve işlem döndürmez. Tam giriş yükünü denetlemek ve alan varlığını doğrulamak için
app function replay'i kullanın. - Dev Dashboard bir çalıştırma gösterir ancak ayrıntı yok: Uygulama, giriş sorgusu tarafından gerektirilen en az bir kapsamı kaçırıyor. Yukarıdaki kapsam kontrol listesine bakın.
- Yerel
app function rundoğru çıkış döndürür ancak geliştirme mağazası sonucu uygulamaz: CLI'nin yerel olarak çalıştırdığı derlenmiş Wasm ikilisi bayat olabilir.app function runçalıştırmadan önce açıkçashopify app function buildçalıştırın. app devuygulama günlükleri paneli "Uygulama günlükleri yoklanırken hata, 5 saniyede yeniden deneniyordu" gösterir: CLI 4.7.x ve 4.8.x'de bilinen aralıklı bir sorun. Fonksiyon hala çalışır ve günlük dosyalarını.shopify/logs/'a yazar; akış paneline bağlı kalmak yerine bu dosyalara karşıapp function replaykullanın.InvalidInputQueryErrorDev Dashboard'da: Giriş sorgunuz, fonksiyonunuzunshopify.extension.tomlbildirdiği API sürümü için var olmayan bir alana başvuruyor.shopify app function typegençalıştırıp geçerli şemaya karşı türleri yeniden oluşturun, sonra karşılaştırın.
İş akışını bir araya getirme
Bir fonksiyon hatalı davrandığında çalıştırdığım dizi:
shopify app function buildtaze bir.wasmikilisi almak için.shopify app devbir geliştirme mağazasına karşı; ilgili ödeme akışını bir kez tetikleyin.- Altı karakterli günlük kimliğini kopyalayın terminal çıkışından.
shopify app function replay --log <id>izleme modunda; fonksiyonu düzenleyin; CLI her kaydedişte yeniden derler ve çalıştırır.- Yerel çıkış doğru göründüğünde, talimat sayısı ve geliştirme mağazası çalıştırmasından günlük çıkışı için Dev Dashboard kontrol edin.
- Bir üretim arızası için: Dev Dashboard çalıştırmasından girişi dışa aktarın,
fixtures/prod-failure.jsonolarak kaydedin veapp function runile--input fixtures/prod-failure.jsonkullanarak adım 4'ten tekrarlayın.
Bu döngü en pahalı hata ayıklama anti-desenini ortadan kaldırır: bir değişikliği üretim ortamına dağıtma, satıcının ödeme akışını yeniden tetiklemesini bekleme ve 1 kB'lık bir günlük parçasında ne olduğunu bulmaya çalışma.
sessizce hiçbir şey döndürmüyor ve kök nedeni yeniden oynatma aracılığıyla nasıl izleleyeceğiniz konusunda çalışılmış bir örnek için bu blogun vaka çalışmaları bölümüne bakın.
Ekibinde Shopify geliştiricisi olmayan markalar bu işi Shopify mühendislik stüdyom Lintel'e getirebilir: Shopify Functions geliştirme.
Sıkça sorulan sorular
Fonksiyon çalıştığı halde Dev Dashboard'da fonksiyon çalıştırma günlüğü ayrıntılarını neden göremiyorum?
Dev Dashboard, günlük ayrıntılarını uygulamanızın tuttuğu erişim kapsamları tarafından sınırlar. Shopify, gerekli kapsamları fonksiyonunuzun giriş sorgusu tarafından okunan her alandan türetir. Gerekli kapsam eksikse, çalıştırma meta verilerini görsünüz ancak giriş ve çıkış yükleri gizlenir. Eksik kapsamları shopify.app.toml'a ekleyin ve satıcıdan yeniden talep edin.
app function run ve app function replay arasındaki fark nedir?
app function run, derlenmiş Wasm ikilisini el ile sağladığınız veya armatür dosyasından aldığınız JSON girişine karşı yürütür. app function replay, daha önce günlüğe kaydedilmiş bir gerçek yürütmeden (altı karakterli günlük kimliğiyle tanımlanan) girişi alır ve fonksiyonu buna karşı yeniden çalıştırır, sonra kod değişikliklerini izler ve otomatik olarak yeniden çalıştırır. Replay, giriş yapmanız gerekmediğinden gerçek arızaları hata ayıklamak için daha hızlıdır.
Yerel ortamda çalışan ancak geliştirme mağazasında başarısız olan bir Shopify Fonksiyonunu nasıl hata ayıklayabilirim?
En yaygın nedeni, derlenmiş ikilinin bayat olmasıdır. Yeniden derlemek için shopify app function build'i açıkça çalıştırın, sonra app function run ile yeniden test edin. Çıkış hala farklılık gösteriyorsa, yerel armatürünüzün kullandığı tam girişi .shopify/logs'taki app dev tarafından günlüğe kaydedilen giriş ile karşılaştırın: koşullu mantığınızın bağlı olduğu bir alan giriş sorgusu eksik olabilir ve bu nedenle canlı mağazada çalışma zamanında null olabilir.