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.tomldosyasındakiuidalanı 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.--forceolmadanshopify app deploykomutunu çalıştırmak, Dev Dashboard göçten önceki eski uzantılara uid'ler damgalamak için önerilen tek seferlik adımdır.shopify app devsırasındaBeklenmeyen JSON sonuhatası neredeyse her zaman boş veya eksikshopify-cli-theme-conf-nodejsyapılandırma dosyasından kaynaklanır, Liquid veya TOML dosyalarından değil..shopifyklasörünü silmek veshopify app devkomutunu 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ş
.tomldosyaları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
uidolmayan uzantılara sahiptir. --forcekullanan CI/CD boru hatları. Bir konteynerdenshopify 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
| Hata | Temel neden | İlk kontrol | Çözüm |
|---|---|---|---|
uid tanımlayıcıları shopify app dev sırasında | Uzantı TOML'si uid alanı içermiyor | shopify.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 sonra | Eski .shopify oturum önbelleği | Proje kökünde .shopify/ var mı? | .shopify/ dosyasını silin ve shopify app dev komutunu yeniden çalıştırın |
Beklenmeyen JSON sonu | Boş shopify-cli-theme-conf-nodejs dosyası | Dosyada cat çalıştırın; boş çıktı bunu doğrular | Dosyaya {} yazın, sonra shopify app dev komutunu yeniden çalıştırın |
| uid geçişinden sonra uzantı Theme Editor'de görünmüyor | include_config_on_deploy true olarak ayarlanmadı | shopify.app.toml dosyasında özelliği kontrol edin | include_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şmiyor | TOML uid'yi Ortak (Partner) Panosu uzantı kimliğiyle karşılaştırın | Panodan 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.tomlbu alt dizinin kökünde olmalıdır;blocks/içinde veya başka herhangi bir yerde iç içe geçmiş değildir.uidalanı 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:
- uid damgalı dağıtımı bir yerel makinedan çalıştırın, etkileşimli olarak,
--forceolmadan. - Güncellenmiş TOML dosyalarını kaynak denetimine işleyin hemen. CI boru hattı bunları bir sonraki çalıştırmada alır.
- Boru hattı normal olarak
--forcekullanmaya devam eder. UID'ler artık işlenmiş TOML'lere gömülü olduğundan, etkileşimli istem gerekmez. - 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 extensionkomutunu ç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--forcekomutunu 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.
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.