【Astro】Astro 6 から 7 へ移行したときに起きた4箇所の問題と直し方

Astro 7 に上げたらビルドが止まったときの直し方

• experimental フラグを設定していると、v7 では設定検証の段階でビルドが止まる
• v6 ではエラーにならなかった閉じ忘れタグが CompilerError になる
• エラーは出ないのにインライン要素の間の空白が消えて表示が変わる

対象読者: Astro 6 で運用中のサイトやブログを v7 に上げたい技術者。

前提知識: .astro コンポーネントと astro.config.mjs の基本。

結論

実際の v6 プロジェクトを v7 に上げたところ、4箇所でエラーや表示の変化が出ましたが、どれも直せるものでした。まず npx @astrojs/upgrade で本体と公式インテグレーションを一括更新してから、出てきたエラーを順に直せば移行は完了です。

# 本体と公式インテグレーションを一括更新
npx @astrojs/upgrade

# 出てきたエラーを順に潰す（各エラーと直し方は本文で実測付き）
npm run build

# remark / rehype プラグインを使っている場合だけ必要
npm install @astrojs/markdown-remark

移行前の下準備として、v7 への移行で問題が出やすい設定の有無を grep で洗い出しておくと快適です。

grep -rn "experimental" astro.config.mjs src/
grep -rn "@astrojs/db|astro:transitions" src/
npm ls @astrojs/markdown-remark

Astro 7 で変わった中身

v7 の中心はコンパイラと Markdown 処理の作り替えです。公式のアップグレードガイドに挙げられている変更はこの通り。

• Rust 製コンパイラが唯一のコンパイラに。閉じ忘れタグや不正な HTML の扱いが厳格化
• Markdown の既定処理が remark / rehype から Sätteri に。実体は @astrojs/markdown-satteri パッケージ
• compressHTML の既定値が true から 'jsx' に。インライン要素間の空白が消えうる
• バンドラが Vite 8 系に（Astro 7.4.2 の依存は vite@^8.3.4 と rolldown@^1.2.13）
• @astrojs/db の削除、astro:transitions 内部 API の削除など

Node.js の要件も少し上がっています。npm レジストリの engines フィールドを見ると、Astro 6.4.8 は Node.js 22.12.0 以降、7.4.2 は 22.23.4 以降が条件です。

Node 22.12〜22.23.3 の環境は、Astro より先に Node を上げる必要があります。

1. experimental フラグが設定エラーになった

v6 で有効だった experimental.advancedRouting を設定したまま上げると、ビルドより前の設定検証で止まります。

import { defineConfig } from "astro/config";

export default defineConfig({
  experimental: {
    advancedRouting: true, // v6 では有効だった指定
  },
});

実際のエラーはこう出ます。v7 で実験扱いのフラグは残っていないので、削除するしかありません。

$ npm run build

[config] Astro found issue(s) with your configuration:

! Invalid or outdated experimental feature.
  Check for incorrect spelling or outdated Astro version.
  See https://docs.astro.build/en/reference/experimental-flags/ ...

直し方は experimental キーごと消すだけです。対応関係はこうなります。

• advancedRouting / queuedRendering / rustCompiler: v7 では既定で有効なので指定自体が不要
• logger / cache（routeRules 付き）: 安定化してトップレベルへ移動。使っていたら experimental の外に出す

2. 閉じ忘れタグが CompilerError になった

Rust 製コンパイラでは閉じ忘れタグが自動で補完されなくなりました。v6 ではビルドできていたテンプレートが、v7 ではコンパイルエラーになります。

---
const items = ['Alpha', 'Beta', 'Gamma'];
---

<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <title>probe</title>
  </head>
  <body>
    <h1>Astro 6 project</h1>
    <p>unclosed paragraph
    <ul>
      {items.map((item) => <li>{item}</li>)}
    </ul>
    <p>
      <span>hello</span>
      <em>world</em>
    </p>
  </body>
</html>

実測のエラーはこう出ます。

$ npm run build

[ERROR] [vite] ✗ Build failed in 90ms
[CompilerError] Expected corresponding JSX closing tag for 'p'.

直し方はエラーの言うとおり、閉じタグを補うだけです。もう1つだけ注意点があって、v6 は <p> の中の <div> のような不正な入れ子も自動で修正していました。

v7 ではそのまま出力されるため、ブラウザの解釈でレイアウトが変わる可能性があります。生成 HTML をいくつか目視確認しておくと安心です。

3. インライン要素間の空白が消えた

これだけはエラーが出ないので見落としやすいです。次のようなマークアップを考えます。

<p>
  <span>hello</span>
  <em>world</em>
</p>

compressHTML の既定値が 'jsx' に変わったため、JSX と同じルールで空白が除去されます。ビルド後の HTML を v6 と v7 で比較するとこうなります。

# v6（compressHTML: true が既定）
<span>hello</span> <em>world</em>

# v7（既定の 'jsx'。span と em の間の空白が消える）
<span>hello</span><em>world</em>

ブラウザでは「hello world」が「helloworld」に変わります。直し方は2つあります。

• 空白を残したい個所だけ {” “} を明示する（React と同じ考え方）
• v6 と同じ圧縮ルールに戻すなら compressHTML: true を設定する

import { defineConfig } from "astro/config";

export default defineConfig({
  compressHTML: true, // v6 と同じ圧縮ルールに戻す
});

設定リファレンスにある通り、false にすれば空白をすべて保持できます。

4. remark プラグインの設定でビルドが止まった

Markdown 処理が Sätteri に変わった影響で、@astrojs/markdown-remark は既定でインストールされなくなりました。npm ls で v6 と v7 を比較すると、この違いを確認できます。

# v6（astro の依存として入っている）
└─┬ astro@6.4.8
  └── @astrojs/markdown-remark@7.2.0

# v7（空になる）
└── (empty)

markdown.remarkPlugins などを設定していると、v7 では次のエラーで止まります。

import { defineConfig } from "astro/config";
import remarkGfm from "remark-gfm";

export default defineConfig({
  compressHTML: true,
  markdown: {
    remarkPlugins: [remarkGfm],
  },
});

`markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` run on the
`unified` processor from `@astrojs/markdown-remark`, which is no longer installed by default
now that Sätteri is the default Markdown processor. Install it with:
  npm install @astrojs/markdown-remark

直し方はエラーメッセージのとおり、パッケージを入れ直すだけです。詳しい経緯は Markdown ガイドに書かれています。

入れ直してビルドすると、GFM の打ち消し線は従来どおりレンダリングされました。

$ npm install @astrojs/markdown-remark
$ npm run build

# dist/post/index.html から抜粋
<del>strike</del>   # ← gfm-ok

つまずきポイント

今回の実測では出ませんでしたが、移行時に確認しておきたい削除・変更は他にもあります。

• @astrojs/db: 削除。Astro DB を使っている場合は Node 標準の node:sqlite（Node 22.5+）や Drizzle などへの移行が必要
• astro:transitions: TRANSITION_* 定数・isTransition*() 判定・createAnimationScope() が削除。イベント名の文字列（'astro:after-swap' など）へ置き換える
• getContainerRenderer(): @astrojs/react などのパッケージルートからの import が非推奨に。@astrojs/react/container-renderer のような /container-renderer から取る
• src/fetch.ts: 予約ファイル名に。同名ファイルがあると advancedRouting が自動で読み込む
• CSS のシリアライズ: 色の表記や url() の引用符が変わる。CSS を文字列一致で検証しているテストは落ちる可能性がある

検証環境

上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。

まとめ

v6 から v7 への移行で実際に出た4箇所の問題と直し方はこの通りです。

どのエラーもメッセージが親切なので、npm run build を繰り返しながら順に直せば1時間もかかりません。上げる前に grep の下準備をしておくと、なお早いですよ。

参考

• Upgrade to Astro v7 — Astro Documentation
• Experimental flags — Astro Documentation
• Markdown & MDX — Astro Documentation
• Configuration reference — Astro Documentation
• Releases · withastro/astro — GitHub

【広告】お名前.comならドメイン取得が格安。

あわせて読みたい

• 【Vite】Vite 8 移行ガイド2026 — Rolldown 統合で壊れる設定
• 【ESLint】.eslintrc から v10 の flat config へ移行したログ — 実際に壊れた4箇所
• Tailwind CSS v4 セットアップ完全ガイド｜Vite + @theme

【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう！！