5 Kasım 2026 · 7 dk okuma

Shopify CLI Theme App Extension Hatalarını Düzeltme: uid Tanımlayıcıları ve Beklenmeyen JSON Sonu

İki Shopify CLI hatası theme app extension geliştirme oturumlarını engeller: eksik uid tanımlayıcıları ve Beklenmeyen JSON sonu.

Shopify CLI Theme App Extension Hatalarını Düzeltme: uid Tanımlayıcıları ve Beklenmeyen JSON Sonu

shopify app dev komutunu theme app extension üzerinde durduran her iki hatanın da belgelenen ve tekrarlanabilir nedenleri vardır. uid tanımlayıcıları hatası, CLI'ın yerel uzantınızı Shopify platformunda bulunan kaydıyla eşleyememesi anlamına gelir; Beklenmeyen JSON sonu hatası genellikle bozulmuş veya boş yerel konfigürasyon dosyasından kaynaklanır. uid sorununu etkileşimli bir dağıtımla çözün; JSON hatasını bozuk yapılandırma dosyasına geçerli bir nesne yazarak çözün.

Temel noktalar

  • shopify.extension.toml dosyasındaki uid alanı uygulamaya özgüdür ve her uzantı için zorunludur; Shopify CLI ile yapı iskelesi kurduğunuzda otomatik olarak oluşturulur ancak kaynak denetimine işlenmelidir.
  • --force olmadan shopify app deploy komutunu çalıştırmak, Dev Dashboard göçten önceki eski uzantılara uid'ler damgalamak için önerilen tek seferlik adımdır.
  • shopify app dev sırasında Beklenmeyen JSON sonu hatası neredeyse her zaman boş veya eksik shopify-cli-theme-conf-nodejs yapılandırma dosyasından kaynaklanır, Liquid veya TOML dosyalarından değil.
  • .shopify klasörünü silmek ve shopify app dev komutunu yeniden çalıştırmak, başarılı bir dağıtımdan sonra bile dev modunda uid atamasını engelleyen eski oturum durumunu çözer.
  • uid damgalı dağıtımdan hemen sonra güncellenmiş .toml dosyalarını kaynak denetimine işleyin; aksi takdirde CLI bir sonraki çalıştırmada uzantıları silmeye ve yeniden oluşturmaya çalışacaktır.

uid alanı gerçekte ne

uid alanı, shopify app deploy komutunun bir uzantının oluşturulup oluşturulmadığını, güncellenip güncelleenmediğini veya silinip silinmediğini belirlemek için kullandığı gerekli ve uygulamaya özgü bir tanımlayıcıdır. Shopify tarafından oluşturulur ve yönetilir: Shopify CLI ile uzantı iskelesi kurduğunuzda otomatik olarak oluşturulur, bu nedenle el ile ayarlamanız veya düzenlemeniz gerekmez.

Bu son cümle tuzaktır. İskelesi kurduğunuzda otomatik olarak oluşturulur, ancak etkileşimli dağıtım sırasında .toml dosyasına geri yazılır. Shopify Dev Dashboard göçünü tanıtmadan önce uzantıyı oluşturduysanız, shopify.extension.toml dosyanızda uid satırı yoktur ve CLI artık dev modunda devam etmeden önce bir satırın varlığını gerekli kılar.

Kullanıcı tanımlayıcıları shopify.extension.toml dosyasında yeni bir uid özelliği olarak görünür ve varsayılan olarak UID, uzantı tanıtıcısına göre belirlenimci bir şekilde ayarlanır, bu nedenle aynı tanıtıcı değerine sahip uzantılar için her zaman aynı olacaktır.

uid şöyle görünür:

name = "my-theme-extension"
type = "theme"
uid = "fddfc370-27c7-c30f-4ee0-a927194e2accadefd40c"

Bu, CLI 2'den .env dosyasında kullanılan eski EXTENSION_UUID ile aynı değildir. Bu UUID, Ortak (Partner) Panosu'nda uzantı kaydını tanımlamak için kullanıldı. uid, yeni nesil Dev Dashboard'un sürümler arasında ekleme, güncelleme ve silme işlemlerini izlemek için kullandığı daha yeni, TOML'de bulunan bir tanımlayıcıdır.

Hata 1: "Uygulamanızın uid tanımlayıcılarına atanması gereken uzantıları var"

Ne zaman görünür

Hata şöyle okunur: Uygulamanızın uid tanımlayıcılarına atanması gereken uzantıları var. shopify app dev komutunu çalıştırdığınızda ve CLI en az bir shopify.extension.toml dosyasını uid alanı olmadan bulduğunda görünür.

Bu iki yaygın durumda ekiplere vurur:

  • Dev Dashboard'a geçirilen eski uygulamalar. CLI 2 üzerinde oluşturulan (Ortak (Partner) Panosu tarafından yönetilen) ve Next-gen Dev Dashboard'a geçen uygulamalar, TOML dosyalarında uid olmayan uzantılara sahiptir.
  • --force kullanan CI/CD boru hatları. Bir konteynerden shopify app deploy --force çalıştırırsanız, bu dağıtımın uzantı TOML'lerinize ekleyeceği UID değerleri hiçbir zaman işlenmez. Shopify, Geliştirici Panosu'nda oturum açıp uygulama sürüm bilgilerinden UID değerlerini alıp uzantı TOML dosyalarınıza eklemenizi önerir; aksi takdirde gelecekteki değişikliklerin uzantılarınızın silinmesine ve yeniden eklenmesine neden olma riski vardır.

Çözüm

Adım 1. CLI'ı en son sürüme güncelleyin. uid geçiş yolu yalnızca güncel araçlarla güvenilirdir.

npm install -g @shopify/cli@latest
# veya homebrew aracılığıyla:
brew upgrade shopify-cli

Adım 2. --force olmadan etkileşimli bir dağıtım çalıştırın:

shopify app deploy

Güncelledikten sonra, proje dizininizden tek bir etkileşimli shopify app deploy çalıştırmanız yeterlidir. Bu özel dağıtım, uzantılarınız için otomatik olarak yeni kalıcı kimlikler (uid'ler) oluşturacak ve bunları shopify.extension.toml yapılandırma dosyalarınıza kaydedecektir; CLI bu değişiklikleri onaylamanız için sizi isteyecektir. Dağıtım başarılı olduktan sonra, bu güncellenmiş .toml dosyalarını kaynak denetiminize işlemeniz çok önemlidir.

Adım 3. shopify app import-extensions komutunu çalıştırdıktan sonra dağıtım Göç yapılacak uzantı yok yazarsa, bu beklenen bir durumdur. Panodan yönetilen uzantıları geçirmek sürecin bir parçasıdır, ancak uzantılarla olan tüm uygulamalar yeni uid tanımlayıcıları atamak için bir uygulama dağıtımı çalıştırmalıdır. import-extensions ve deploy ayrı adımlardır.

Adım 4. Onaylanan bir dağıtımdan sonra shopify app dev hala başarısız olursa, eski oturum önbelleğini silin:

rm -rf .shopify
shopify app dev

Yapmanız gereken tek şey .shopify klasörünü silmek ve konsolda shopify app dev komutunu çalıştırmak ve projeyi ayarlamak için adımları izlemektir (mağazayı seçin, vb.).

Theme app extension'ları için eski UUID koruması

Merchant mağazalara zaten yüklenmiş bir theme app extension'ını geçiriyorsanız, uid mevcut uzantı UUID'sine eşlenmelidir. Temiz bir iskeleden oluşturulan yeni bir UID'ye geçmek yeni bir uzantı kaydedecek ve her merchant yüklemesini mutsuz bırakacaktır.

shopify.app.toml dosyasının include_config_on_deploy özelliğinin true olarak ayarlandığını onaylayın; bu, yeni yapılandırmaların tüm uygulama dağıtımlarına dahil edilmesini sağlar. Ayrıca uzantı UUID'lerinin düzgün şekilde eşlendiğini, UUID'nin shopify.extension.toml dosyasında listelendiğini onaylayın ve uzantı kullanıcı tanımlayıcılarına geçiş kılavuzunu izleyin.

Eski .env dosyasından orijinal UUID'yi kaybettiyseniz, Ortak (Partner) Panosu > Uygulama > Uzantılar'a gidin ve UUID'yi uzantının URL'sinden kopyalayın.

Hata 2: "Beklenmeyen JSON sonu"

Bu, ilk başta bir ağ veya API sorunu gibi görünen bir mesaj olduğu için kafa karıştırıcıdır. Öyle değildir.

Temel neden

Theme app extension'ı iskelesi kurulduktan sonra başka hiçbir değişiklik yapılmadan shopify app dev komutunu çalıştırmak Beklenmeyen JSON sonu hatası ile çöker. ~/Library/Preferences/shopify-cli-theme-conf-nodejs içindeki yapılandırma dosyası boştu ve bu hataya neden oldu.

CLI bu dosyayı başlangıçta okur ve theme dev sunucusu için tercihleri geri yükler (önizleme şifresi ve son kullanılan mağaza gibi şeyler). Dosya varsa ancak boşsa, JSON.parse uygulama işlemi tam olarak başlamadan SyntaxError: Beklenmeyen JSON sonu hatası oluşturur. Hata satır numarası olmadan yükselir, bu nedenle ölümcül görünür.

Nedeni doğrulama

# macOS
cat ~/Library/Preferences/shopify-cli-theme-conf-nodejs
# Çıktı boşsa, bu sizin sorununuzdur.

Linux'te aynı dosya genellikle ~/.config/shopify/shopify-cli-theme-conf-nodejs altında veya XDG yapılandırma ana dizini altında bulunur.

Çözüm

Dosyaya boş bir nesne ekleyin ve kaydedin. shopify app dev komutunu orijinal uygulama dizininizden çalıştırın; bu sefer dev mağazasının önizleme şifresi sorulacaktır ve bu şifreler geçerli bir değeri yapılandırma dosyasına kaydedecek ve uygulamayı başka sorun olmadan çalıştıracaktır. Bu muhtemelen yerel geliştirme ortamında bozulmuş boş bir yapılandırma dosyasından kaynaklanan bir yapılandırma sorunuydu.

echo '{}' > ~/Library/Preferences/shopify-cli-theme-conf-nodejs
shopify app dev

Mağaza önizleme şifresini girdikten sonra, dosya geçerli JSON ile yeniden yazılır ve hata kalıcı olarak kaybolur.

Hata karşılaştırma tablosu

HataTemel nedenİlk kontrolÇözüm
uid tanımlayıcıları shopify app dev sırasındaUzantı TOML'si uid alanı içermiyorshopify.extension.toml bir uid = satırı içeriyor mu?shopify app deploy komutunu etkileşimli olarak çalıştırın, sonra TOML'leri işleyin
uid tanımlayıcıları dağıtım başarılı olduktan sonraEski .shopify oturum önbelleğiProje kökünde .shopify/ var mı?.shopify/ dosyasını silin ve shopify app dev komutunu yeniden çalıştırın
Beklenmeyen JSON sonuBoş shopify-cli-theme-conf-nodejs dosyasıDosyada cat çalıştırın; boş çıktı bunu doğrularDosyaya {} yazın, sonra shopify app dev komutunu yeniden çalıştırın
uid geçişinden sonra uzantı Theme Editor'de görünmüyorinclude_config_on_deploy true olarak ayarlanmadıshopify.app.toml dosyasında özelliği kontrol edininclude_config_on_deploy = true olarak ayarlayın ve yeniden dağıtın
CLI yükseltmesinden sonra app embed bozuk (uid otomatik eklendi)TOML'deki UID, dağıtılan uzantı kaydıyla eşleşmiyorTOML uid'yi Ortak (Partner) Panosu uzantı kimliğiyle karşılaştırınPanodan orijinal UUID'yi eşleyin, TOML'yi güncelleyin, yeniden dağıtın

Her iki hatayı da önleyen dizin yapısı

Theme app extension'ı olan bir Remix uygulaması için CLI'ın beklediği şöyledir. Özellikle eksik shopify.extension.toml veya yanlış dizinde bulunan TOML, CLI'ın uzantıyı tamamen atlaması veya çökmesine neden olan herhangi bir sapma.

my-app/
├── shopify.app.toml          # include_config_on_deploy = true
├── package.json
└── extensions/
    └── my-theme-extension/
        ├── shopify.extension.toml   # uid = "..."
        ├── blocks/
        │   └── my-block.liquid
        ├── snippets/
        └── assets/

Temel yapısal kurallar:

  • Her uzantı extensions/ altında kendi alt dizininde bulunur.
  • shopify.extension.toml bu alt dizinin kökünde olmalıdır; blocks/ içinde veya başka herhangi bir yerde iç içe geçmiş değildir.
  • uid alanı mevcut olmalı ve Shopify platformunda mevcut uzantılar için depolanan değerle eşleşmelidir.
  • Theme app extension'ları için özel olarak, type "theme_app_extension" değil (eski CLI 2 değeri), "theme" olmalıdır.

CI/CD'ye uygun uid iş akışı

Boru hattınız --force kullanırsa, uid damgalamayı onaylamanız için hiçbir zaman etkileşimli olarak istenmeyecek ve disk üzerindeki TOML dosyalarınız sessizce uid'siz kalacaktır. Koruduğum uygulama projelerinde bunu şu şekilde ele alırım:

  1. uid damgalı dağıtımı bir yerel makinedan çalıştırın, etkileşimli olarak, --force olmadan.
  2. Güncellenmiş TOML dosyalarını kaynak denetimine işleyin hemen. CI boru hattı bunları bir sonraki çalıştırmada alır.
  3. Boru hattı normal olarak --force kullanmaya devam eder. UID'ler artık işlenmiş TOML'lere gömülü olduğundan, etkileşimli istem gerekmez.
  4. Boru hattının yeni bir iskeleler oluşturmasına hiçbir zaman izin vermeyin. Bir ekip üyesi yeni bir uzantı için shopify app generate extension komutunu çalıştırırsa, ortaya çıkan TOML hiçbir zaman dağıtılmamış otomatik oluşturulmuş bir UID'ye sahip olacaktır. Bu tamam, ancak CI boru hattının --force komutunu güvenli bir şekilde kullanabilmesi için yerel bir etkileşimli dağıtıma ihtiyaç duyar.

CLI'ın uzantı tanımlayıcılarını platform kayıtlarıyla nasıl eşlediği hakkında daha derinlemesine bilgi için, bkz. uzantı UID'leri hakkındaki sözlük girişim.

Sonuç

Her iki hata da ilk başta denk geldiğinde opak görünür, ancak dar ve iyi tanımlanmış nedenleri vardır. uid hatası Shopify'ın next-gen Dev Dashboard'a geçişinden kaynaklanan bir geçiş yapıtıdır ve JSON hatası bozulmuş yerel tercih dosyasıdır. Ne Liquid'de, ne de uygulama mantığında, ne de uid alanını eklemenin ötesinde TOML yapısında değişiklik yapılması gerekmez. Etkileşimli dağıtımı çalıştırın, ortaya çıkan TOML dosyalarını işleyin, gerekirse bozuk yapılandırma dosyasına {} yazın ve her iki sorun kapanır.

Bunu şirket içinde yapmak yerine yaptırmak isterseniz, yönettiğim stüdyo Lintel bu tür projeler için özel Shopify uygulama geliştirme sunuyor.

shopify clitheme app extensionshopify app devhata ayıklamaextensions

Sıkça sorulan sorular

shopify.extension.toml dosyasındaki uid alanı nedir ve nereden gelir?

uid, her uzantının shopify.extension.toml dosyasına yazılan gerekli ve uygulamaya özgü bir tanımlayıcıdır. Shopify CLI ile yeni bir uzantı iskelesi kurduğunuzda otomatik olarak oluşturulur veya Dev Dashboard göçünün bir parçası olarak etkileşimli shopify app deploy komutu sırasında mevcut uzantılara damgalanır. Bunu asla el ile düzenlemelisiniz.

shopify app deploy başarılı olur ancak shopify app dev hala uid hatasını gösteriyor?

Başarılı bir dağıtım uid'yi disk üzerindeki TOML dosyalarınıza yazar, ancak proje kökünüzdeki .shopify klasörü uid'nin varolmadığı önceki oturum durumunu önbelleğe alır. .shopify klasörünü silin ve shopify app dev komutunu yeniden çalıştırarak güncellenmiş TOML değerlerini alın ve yeni bir oturum başlatın.

Aynı uid'yi birden fazla uygulama veya mağaza arasında yeniden kullanabilir miyim?

Hayır. uid uygulamaya özgüdür, yani yerel uzantı dizininizi Shopify platformundaki bir uzantı kaydıyla benzersiz olması gerekir. uid'yi başka bir uygulamadan veya başka bir uzantıdan kopyalamak, CLI'ın yanlış uzantı kaydıyla dağıtım sırasında üzerine yazmasına veya çakışmasına neden olacaktır.

Yedi yıllık Shopify, tek sayfada.

Roller, projeler, teknoloji yığını ve sertifikalar özgeçmişte.

Özgeçmiş PDF indir LinkedIn