Prima di montare EmDash su un sottopercorso: abbiamo cliccato ogni indirizzo sotto /field-notes

Dopo aver impostato base in Astro, quali indirizzi si spostano con esso e quali no, più alcuni punti da controllare a mano prima di andare online.

Mettere un sito sotto example.com/field-notes/ invece di dargli un dominio intero è un’esigenza comune: il sito principale è un altro sistema e il blog è solo una sezione appesa sotto.

L’impostazione corrispondente in Astro è una sola riga, base. Per questo pensavamo che questa guida sarebbe stata breve.

Poi abbiamo creato un nuovo sito con il template del blog, impostato base: "/field-notes", fatto la build, avviato e chiamato ogni indirizzo con curl. C’era più da dire di quella singola riga. Ecco cosa abbiamo visto davvero.

Ambiente di test: EmDash 1.4.0, adattatore Node, SQLite, template del blog ufficiale, con gli 8 articoli di esempio del template caricati tramite emdash seed.

export default defineConfig({
  output: "server",
  base: "/field-notes",
  // ...
});

Quali indirizzi si sono spostati con base?

Prima la buona notizia. Le pagine in sé vanno bene:

IndirizzoRisultato
/field-notes/200
/field-notes/posts200
/field-notes/rss.xml200
/field-notes/robots.txt200

Quali indirizzi sono rimasti dove erano?

L’amministrazione e l’API restano al loro posto:

IndirizzoRisultato
/_emdash/api/health200
/_emdash/admin302, reindirizza a /_emdash/admin/setup

In altre parole, tutto ciò che inizia con /_emdash non si sposta dentro /field-notes. La regola di instradamento che hai davanti deve inviare a questa applicazione sia /field-notes/* sia /_emdash/*. Se invii solo la prima, l’amministrazione non si apre.

Altri due indirizzi in cui ci siamo imbattuti meritano una menzione: /field-notes/_emdash/api/health e /field-notes/sitemap.xml restituiscono entrambi 500. Non sono indirizzi che qualcuno dovrebbe visitare, ma se il tuo script di verifica funziona con il principio «aggiungi il prefisso e riprova», ti spaventeranno.

Un’altra cosa ci ha sorpreso: anche il percorso radice / e /posts restituiscono 200. Lo stesso contenuto ha quindi due ingressi. Se non vuoi che i motori di ricerca vedano due copie, fai passare dal tuo instradamento iniziale solo /field-notes/* e /_emdash/* e rifiuta tutto il resto.

Questo è il punto che ci aspettavamo di meno. Apri la home a /field-notes/ e guarda il sorgente. I link sono fatti così:

  • 7 articoli: cose come /posts/a-weekend-with-a-side-project
  • 4 tag: cose come /tag/opinion
  • la barra di navigazione: /, /pages/about, /posts
  • più /rss.xml e /search

Nessuno porta /field-notes. Cliccando si esce dal tuo sottopercorso e si finisce sotto il percorso radice.

I link provengono da due posti e si correggono in punti diversi:

  1. Scritti direttamente nel codice del template. Per esempio href={`/tag/${t.slug}`} in src/pages/posts/[slug].astro e il href="/posts" che compare in diverse pagine. Vanno riscritti in modo che inizino con import.meta.env.BASE_URL.
  2. Memorizzati nel database. Le tre voci di navigazione non sono scritte nel template. Sono dati di menu, conservati nella tabella _emdash_menu_items, e i loro indirizzi sono /, /pages/about e /posts. Se modifichi solo il template, la barra di navigazione non si muove affatto. Devi cambiare gli indirizzi delle voci di menu stesse, oppure cambiare il file di seed e ricaricarlo.

Il modo in cui questi link sono scritti in questo template è una scelta del template stesso. Non è un problema causato dall’impostazione base. Inoltre non abbiamo riscritto l’intero template per poi verificarlo, quindi qui possiamo solo dirti dove cercare. Non possiamo promettere che tutto sia corretto dopo averli modificati.

Anche gli indirizzi letti dalle macchine non hanno prefisso

Oltre ai link che vedono le persone, ci sono tre cose lette dalle macchine, e abbiamo guardato anche quelle:

  • Gli indirizzi elencati in /sitemap.xml sono del tipo .../sitemap-posts.xml, e gli indirizzi degli articoli al loro interno del tipo .../posts/the-case-for-static. Nessuno contiene /field-notes.
  • Il <link> di ogni voce del feed RSS è allo stesso modo .../posts/....
  • Il /robots.txt alla radice contiene Disallow: /_emdash/ e punta alla sitemap, mentre /field-notes/robots.txt contiene solo User-agent: * e Allow: /, senza il blocco di /_emdash/ e senza la sitemap.

L’ultimo punto merita una riflessione: i motori di ricerca leggono robots.txt solo alla radice del dominio. Quello sotto il sottopercorso, in pratica, non lo legge nessuno. Se il tuo sito principale non è EmDash, devi bloccare tu stesso /_emdash/ nel robots.txt del sito principale.

L’assenza di prefisso nella sitemap e nell’RSS significa che gli indirizzi che invii ai motori di ricerca saranno indirizzi fuori dal sottopercorso. Abbiamo solo osservato il comportamento. Non abbiamo cercato quale riga di codice lo determini.

La modalità di sviluppo ti inganna

Abbiamo iniziato testando con astro dev, e questo è quello che è uscito:

  • /_emdash/api/health ha restituito 500, con Cannot read properties of undefined (reading 'registry') nel log.
  • /sitemap.xml ha restituito 500, con il contenuto EmDash not configured.

Pensavamo che base avesse rotto il runtime. Quando abbiamo tolto base, entrambi gli indirizzi sono tornati a 200, il che ci ha convinto ancora di più.

Finché non siamo passati a eseguire prima astro build e poi ad avviare con node ./dist/server/entry.mjs. Con base impostato, i due indirizzi di sopra restituiscono 200.

Quindi non usare la modalità di sviluppo per giudicare se un sottopercorso è configurato correttamente. Non abbiamo scoperto perché le due modalità differiscano.

Cosa cliccheremmo a mano prima di andare online

  1. Fare la build, avviare e guardare con curl il sorgente della home di /field-notes/. Cercare i link che iniziano con href="/ ma non contengono /field-notes.
  2. Aprire /_emdash/admin e confermare che la regola di instradamento davanti lo invii all’applicazione.
  3. Dare un’occhiata agli indirizzi in sitemap.xml e rss.xml.
  4. Confermare nel robots.txt del sito principale che /_emdash/ sia bloccato.
  5. Visitare / e /posts e decidere se vuoi che esistano.

Cosa non abbiamo testato

  • Non abbiamo messo la regola di instradamento su un vero Cloudflare Worker o nginx. Quanto detto sopra sul dover inviare sia /field-notes/* sia /_emdash/* è dedotto dal comportamento osservato.
  • Non abbiamo provato l’adattatore Cloudflare, solo Node.
  • Non abbiamo riscritto i link in tutto il template.

Se puoi fare a meno di un sottopercorso e usare un sottodominio separato, eviti la maggior parte di ciò di cui parla questo articolo.