在独立TSX脚本中导入astro:content时出现ERR_UNSUPPORTED_ESM_URL_SCHEME错误

问题核心原因 #

astro:content是Astro提供的虚拟模块，仅在Astro的开发/构建流程中由自身模块解析器处理。Node.js（包括tsx直接运行脚本时使用的默认ESM加载器）无法识别astro:这种自定义协议的模块路径，因此抛出ERR_UNSUPPORTED_ESM_URL_SCHEME错误。

可行解决方案 #

方案1：直接读取内容集合文件（推荐，适合流程外脚本） #

既然脚本需要在Astro运行/构建流程外执行，直接读取src/content目录下的原始文件是最直接的方式，无需依赖Astro的虚拟模块。可以用gray-matter库解析Markdown文件的frontmatter：

1. 安装依赖：

npm install gray-matter --save-dev

2. 示例读取照片集合的代码：

import fs from 'node:fs/promises';
import path from 'node:path';
import matter from 'gray-matter';

// 定义照片集合的类型（模拟CollectionEntry的结构）
type PhotoEntry = {
  id: string;
  data: {
    title: string;
    date: string;
    // 其他你定义的frontmatter字段
  };
  body: string;
};

async function getPhotoEntries(): Promise<PhotoEntry[]> {
  const collectionDir = path.join(process.cwd(), 'src/content/photos');
  const files = await fs.readdir(collectionDir);

  return Promise.all(
    files.map(async (file) => {
      const filePath = path.join(collectionDir, file);
      const fileContent = await fs.readFile(filePath, 'utf-8');
      const { data, content } = matter(fileContent);
      // 文件名（去掉后缀）作为id
      const id = path.basename(file, path.extname(file));

      return {
        id,
        data,
        body: content,
      } as PhotoEntry;
    })
  );
}

// 调用示例
getPhotoEntries().then(photos => {
  // 用照片数据生成博客草稿
  console.log('读取到的照片：', photos);
});

方案2：在Astro构建流程内执行脚本 #

如果需要复用Astro的内容解析逻辑（比如自动处理类型、集合配置），可以把脚本逻辑放到Astro的集成或构建钩子中，这样就能正常使用astro:content的API：

1. 在项目根目录创建scripts/generate-draft.ts：

import { getEntry, getCollection } from 'astro:content';

export default async function generateBlogDraft() {
  // 正常使用astro:content的API
  const photos = await getCollection('photos');
  // 生成博客草稿逻辑
  console.log('照片集合数据：', photos);
}

2. 在astro.config.mjs中添加构建钩子：

import { defineConfig } from 'astro/config';
import generateBlogDraft from './scripts/generate-draft';

export default defineConfig({
  hooks: {
    'build:start': async () => {
      await generateBlogDraft();
    },
  },
});

3. 运行Astro构建命令触发脚本：

npm run build

方案3：自定义Node ESM加载器（不推荐） #

编写自定义加载器来处理astro:协议，但需要适配Astro内部的模块解析逻辑，实现复杂且容易随Astro版本更新而失效，仅作为备选方案。

内容的提问来源于stack exchange，提问作者Paskal