Hugo/Hexo/Next.jsからAstroへ移行：3日で完了する詳細ガイド

はじめに

ブログを開くたびに表示が遅くてモヤモヤする。Hugo のテンプレートに少し機能を足そうとして、構文の難しさに辟易する。Next.js で組んだ静的ブログなのに、JavaScript バンドルが巨大で「ただのブログなのに、なぜこんなにコードが必要？」と感じる——そんな経験はありませんか。

私も同じ悩みを抱えていました。そこで耳にしたのが Astro です。PageSpeed Insights で 100 点が狙えるという話。最初は半信半疑でしたが、移行経験を共有する開発者が増え、「そこまで大変ではない」と聞いて興味が湧きました。

ただ、本当に移行する段階になると不安も残ります。

1. 移行は大変か？ 記事が数十〜数百ある場合、1本ずつ直すのか？
2. SEO は大丈夫か？ URL が変わったらどうする？
3. 事前に知っておくべき落とし穴は？ 途中で止まりたくない。

この記事は、そうした不安に答えるためのものです。Hugo、Hexo、Next.js の3つから Astro へ移行する手順、落とし穴、ベストプラクティスをまとめます。多くの開発者経験では、移行は 1〜3日 で完了します。

Astro へ移行する価値

流行に乗るためではなく、実利があるから移行する人が多いです。

Astro のコアメリット

ゼロ JavaScript 戦略

Astro の最大の特徴は「デフォルトで JS ゼロ」です。生成されるページには、原則として JavaScript が含まれません。ブログやドキュメントサイトのようなコンテンツ中心サイトでは、これが性能最適化の究極策になります。

ある開発者は、Next.js から Astro へ移行後、PageSpeed Insights が 85 点から 100 点 に上がり、何度測っても 100 点だったと共有しています。主な要因は次の2点です。

• hydration に必要だった JavaScript の削除
• CSS のインライン化によるネットワークリクエスト削減

Islands アーキテクチャ

とはいえ、コメント欄、検索、テーマ切替など、インタラクションは必要です。Astro は Islands アーキテクチャで対応します。静的 HTML の海の中に、必要なコンポーネントだけ JavaScript の「島」を置きます。

モダンな開発体験

Hugo の Go テンプレートの難しさを知っているなら、Astro の .astro（JSX に近い構文）の扱いやすさがわかるはずです。React、Vue、Svelte のコンポーネントもそのまま使えます。

あるブロガーは「Hugo はテンプレート調整が難しいが、Astro はモダンなフロントエンドの感覚でカスタマイズしやすい」と述べています。

他フレームワークとの比較

移行に向くプロジェクト

向いている例：

• 個人ブログ、技術ブログ
• ドキュメント、ナレッジベース
• 企業サイト、製品紹介
• ポートフォリオ

向いていない例：

• ダッシュボードのような高インタラクション SPA
• リアルタイム更新が多いアプリ
• クライアント状態管理が中心のアプリ

「コンテンツが主役」なら Astro が合います。大量のインタラクションとリアルタイム更新が必要なら、Next.js や SPA フレームワークのままが無難です。

移行前の準備

いきなり手を動かす前に、次を済ませておくとスムーズです。

1. 既存プロジェクトのバックアップ

最重要です。git ブランチで管理するのがおすすめです。

# 移行用ブランチを作成
git checkout -b migrate-to-astro

# 作業内容を保存
git add .
git commit -m "バックアップ：Astro 移行開始"

問題が起きても、いつでも元のブランチに戻せます。

2. 移行工数の見積もり

コンテンツ：

• 記事数：____ 本
• Markdown：標準 / 拡張
• 画像数：____ 枚
• 画像パス：相対 / 絶対

目安：

• 50 本未満：1日
• 50〜200 本：2日
• 200 本以上：3日

3. Astro テーマの選定

既存ブログに近いテーマを選ぶと工数が減ります。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

おすすめ：

• AstroPaper：シンプルな技術ブログ向け
• Fuwari：多言語対応、機能豊富
• Astro Cactus：目次コンポーネント付き

# AstroPaper
npm create astro@latest my-blog -- --template satnaing/astro-paper

# Fuwari
npm create astro@latest my-blog -- --template saicaca/fuwari

4. 環境準備

• Node.js：v18.14.1 以上
• パッケージマネージャー：npm / pnpm / yarn
• VS Code 拡張：Astro（公式、必須）

Hugo からの詳細な移行手順

Hugo ユーザーが多いので、まずここから。難易度は中程度で、主な作業はテンプレート変換です。

ステップ1：Astro プロジェクトの作成

npm create astro@latest my-new-blog
cd my-new-blog
npm install

# よく使う統合
npx astro add mdx sitemap

ステップ2：Markdown コンテンツの移行

最重要ステップです。Hugo と Astro の frontmatter は多くが互換で、数フィールドの変更で済むことが多いです。

frontmatter の対応：

# Hugo
---
title: "私の記事"
date: 2023-01-15
tags: ["フロントエンド", "Astro"]
---

# Astro（⬅ は変更点）
---
title: "私の記事"
pubDate: 2023-01-15  ⬅ date → pubDate
tags: ["フロントエンド", "Astro"]
---

記事が多い場合はスクリプトで一括置換できます。

# macOS/Linux
find content -name "*.md" -exec sed -i '' 's/^date:/pubDate:/g' {} +

# Windows (PowerShell)
Get-ChildItem content -Filter *.md -Recurse | ForEach-Object {
    (Get-Content $_.FullName) -replace '^date:', 'pubDate:' | Set-Content $_.FullName
}

ステップ3：テンプレート変換のコツ

Hugo は Go Template、Astro は JSX ライクです。以前 HTML テンプレートを書いていれば、その HTML を .astro に貼るだけで 70% 近く進むこともあります。

Hugo の例：

{{ range .Pages }}
  <article>
    <h2>{{ .Title }}</h2>
    <p>{{ .Summary }}</p>
  </article>
{{ end }}

Astro 変換後：

---
const posts = await Astro.glob('../pages/blog/*.md');
---

{posts.map(post => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
  </article>
))}

構文がモダンになったと感じるはずです。

ステップ4：画像と静的アセット

Hugo の static/ を Astro の public/ にコピーし、パスはそのままにします。

cp -r hugo-blog/static/* astro-blog/public/

記事内の /images/pic.jpg のような参照は、多くの場合変更不要です。

ステップ5：URL リダイレクト

SEO に直結します。URL 構造が変わる場合は 301 リダイレクト を必ず設定してください。

astro.config.mjs の例：

export default defineConfig({
  redirects: {
    '/old-path': '/new-path',
    '/posts/[slug]': '/blog/[slug]',
  }
})

Hexo からの詳細な移行手順

Hexo も Hugo と似ていますが、固有の注意点があります。

ステップ1：プロジェクト作成と Content Collections

pnpm create astro@latest my-blog --template satnaing/astro-paper
cd my-blog
pnpm install

Astro は Content Collections でコンテンツを管理します。src/content/config.ts でスキーマを定義します。

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
    tags: z.array(z.string()),
  }),
});

export const collections = { blog };

frontmatter がスキーマと合わないとビルド時にエラーになり、品質管理に役立ちます。

ステップ2：コンテンツと画像の移行

Hexo の source/_posts/ を Astro の src/content/blog/ へコピーし、date を pubDate に置換します。

find src/content/blog -name "*.md" -exec sed -i 's/^date:/pubDate:/g' {} +

画像は次の2通りです。

方法1：public/ に置く（簡単・推奨）

cp -r hexo-blog/source/images astro-blog/public/images

記事内のパスはそのままで大丈夫です。

方法2：Astro Image コンポーネント（性能重視）

---
import { Image } from 'astro:assets';
import myImage from '../assets/pic.jpg';
---

<Image src={myImage} alt="説明" />

ステップ3：URL パスのリダイレクト

Hexo のデフォルトは /YYYY/MM/DD/post-name/、Astro のデフォルトは /blog/post-name/ です。

元の形式を維持するか、変える場合は astro.config.ts でリダイレクトを設定します。

export default defineConfig({
  redirects: {
    '/:year/:month/:day/:slug': '/blog/:slug',
  }
})

ステップ4：RSS 全文出力

Hexo はデフォルトで全文 RSS ですが、Astro では設定が必要です。

npx astro add rss

src/pages/rss.xml.js の例：

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
import { marked } from 'marked';

export async function GET(context) {
  const posts = await getCollection('blog');

  return rss({
    title: '私のブログ',
    description: 'ブログの説明',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      link: `/blog/${post.slug}/`,
      content: marked.parse(post.body), // 全文
    })),
  });
}

Next.js からの詳細な移行手順

Next.js からの移行はやや複雑です。ただし SSG モードなら難易度は下がります。

ステップ1：アーキテクチャの違いを理解する

主な違い：

• Next.js：SPA 寄り、グローバルな _app.js がある
• Astro：MPA、ページごとに独立

共通点：

• JSX 構文
• ファイルシステムルーティング
• SSG / SSR 両対応

心構えとしては、「Next.js アプリをそのまま移植する」のではなく、Astro で コンテンツサイトを再構築する イメージが近いです。

ステップ2：プロジェクト作成と React 統合

npm create astro@latest my-blog
cd my-blog
npx astro add react

React 統合を入れれば、既存の React コンポーネントをそのまま使えます。

ステップ3：コンポーネント移行戦略

.jsx / .tsx はそのままコピー可能です。

Next.js コンポーネント（変更なし）：

// components/Button.jsx
export default function Button({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>
}

Astro での利用：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

---
import Button from '../components/Button.jsx';
---

<Button client:load>クリック</Button>

client:load は、このコンポーネントに JavaScript が必要だと Astro に伝えます（デフォルトは静的）。

ステップ4：React から Astro コンポーネントへ

インタラクション不要なコンポーネントは .astro にすると性能が上がります。

React：

export default function Card({ title, description }) {
  const formattedDate = new Date().toLocaleDateString();

  return (
    <div className="card">
      <h2>{title}</h2>
      <p>{description}</p>
      <span>{formattedDate}</span>
    </div>
  );
}

Astro：

---
const { title, description } = Astro.props;
const formattedDate = new Date().toLocaleDateString();
---

<div class="card">
  <h2>{title}</h2>
  <p>{description}</p>
  <span>{formattedDate}</span>
</div>

主な違い：className → class、props は Astro.props、ロジックは --- 内に記述。

ステップ5：Hydration 戦略の調整

Next.js はデフォルトで hydration しますが、Astro はデフォルトではしません。インタラクティブにしたいコンポーネントだけ指定します。

主なディレクティブ：

• client:load — ページ読み込み時に hydrate
• client:idle — アイドル時
• client:visible — ビューポートに入ったとき
• client:only — クライアントのみ

---
import Counter from '../components/Counter.jsx';
import HeavyChart from '../components/HeavyChart.jsx';
---

<!-- すぐに操作可能 -->
<Counter client:load />

<!-- 遅延読み込みで性能向上 -->
<HeavyChart client:visible />

使い分けが性能に直結します。

ステップ6：動的ルート

Next.js の getStaticPaths に相当する処理は Astro でもほぼ同じです。

---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

ステップ7：性能改善の比較

移行の最大のメリットのひとつです。

移行前（Next.js SSG）：

• PageSpeed Insights：85 点
• 初回 JS：約 200KB
• Lighthouse Performance：80〜90 点

移行後（Astro）：

• PageSpeed Insights：100 点（安定）
• 初回 JS：約 10KB（インタラクションなしなら 0KB も可能）
• Lighthouse Performance：95〜100 点

主な要因：

• React hydration コストの削減
• CSS インライン化
• JavaScript の按需読み込み

共通の移行ベストプラクティス

どのフレームワークからでも、次は有効です。

1. 段階的移行

一度に全部移す必要はありません。

フェーズ1：パイロット

• 5〜10 記事で試す
• 手順と性能を確認

フェーズ2：全量移行

• 全記事、テンプレート、コンポーネント
• リダイレクトルールの設定

フェーズ3：仕上げ

• 不足機能の追加
• 性能・SEO の最終調整

あるブロガーは、新記事だけ Astro、旧記事は据え置きという段階的移行でリスクを下げたと共有しています。

2. SEO 保護

301 リダイレクト

URL が変わる場合は必須です。

// Vercel: vercel.json
{
  "redirects": [
    { "source": "/old-path/:slug", "destination": "/new-path/:slug", "permanent": true }
  ]
}

// Cloudflare Pages: _redirects
/old-path/:splat /new-path/:splat 301

Sitemap の更新

npx astro add sitemap

astro.config.mjs：

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://yourdomain.com',
  integrations: [sitemap()],
});

検索エンジンへ提出

移行後、Google Search Console と Bing Webmaster Tools に新しい sitemap を送信してください。

3. 画像最適化

npx astro add image

使用例：

---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---

<Image src={cover} alt="カバー画像" width={800} height={600} />

複数サイズ生成、WebP 変換、遅延読み込みが自動で効きます。

4. テストチェックリスト

公開前に確認してください。

コンテンツ：

• 全記事が表示される
• frontmatter が揃っている
• 記事内リンクが有効
• タグ・カテゴリページが動く

リソース：

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

• 画像が読み込める
• CSS が適用されている

機能：

• 検索
• コメント
• RSS

SEO：

• sitemap 生成
• robots.txt
• 旧 URL のリダイレクト

性能：

• PageSpeed Insights
• Lighthouse

ツール例：

• Broken Link Checker — リンク切れ
• PageSpeed Insights — 性能
• Screaming Frog — SEO クロール

よくある問題と解決策

1. ビルドエラー

Could not find Sharp

Astro の画像最適化依存です。

npm install sharp

それでもダメなら、画像最適化を無効化：

export default defineConfig({
  image: {
    service: { entrypoint: 'astro/assets/services/noop' }
  }
})

MDX バージョン不整合

Astro 5.0 では @astrojs/mdx v4.0.0 以上が必要です。

npm install @astrojs/mdx@latest

2. スタイルが効かない

スコープ CSS の問題

Astro の <style> はデフォルトでスコープされます。

<!-- ローカル -->
<style>
  .card { color: blue; }
</style>

<!-- グローバル -->
<style is:global>
  .card { color: blue; }
</style>

Markdown 本文のスタイル

<style is:global>
  .prose h1 { font-size: 2rem; }
  .prose h2 { font-size: 1.5rem; }
  .prose p { margin: 1rem 0; }
  .prose code { background: #f4f4f4; padding: 0.2rem 0.4rem; }
</style>

<article class="prose">
  <Content />
</article>

または Tailwind Typography を利用。

3. サードパーティ連携

コメント（Giscus 例）

<script
  src="https://giscus.app/client.js"
  data-repo="your-username/your-repo"
  data-repo-id="your-repo-id"
  data-category="Announcements"
  data-category-id="your-category-id"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="light"
  data-lang="ja"
  crossorigin="anonymous"
  async>
</script>

Google Analytics

<html>
  <head>
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');
    </script>
  </head>
</html>

4. デプロイ

Vercel：GitHub 連携で Astro を自動認識。

Cloudflare Pages：

• Build command: npm run build
• Output: dist
• Node.js: 18 以上

GitHub Pages：

export default defineConfig({
  site: 'https://username.github.io',
  base: '/repo-name',
})

まとめ

Astro への移行は、思っているより怖くありません。多くの開発者が 1〜3 日 で完了し、満足していると報告しています。

要点の再確認：

1. バックアップ：git ブランチでいつでも戻れるように
2. 段階的移行：数記事で試してから全量へ
3. SEO：301、sitemap、検索順位の保護
4. テスト：リンク、画像、機能の確認
5. 成果：PageSpeed Insights 100 点も現実的

迷っているなら、テストブランチで数記事だけ移行し、性能を測ってから判断するのがおすすめです。合わなければ、元に戻すだけで損はありません。

参考リンク：

• Astro 公式ドキュメント
• Astro Discord コミュニティ
• Astro テーマ一覧

移行がうまくいくことを願っています。困ったことがあれば、コメント欄で気軽に共有してください。