Astro、Astro-DB、TypeScript与NodeJS开发启动报错求助

问题描述 #

使用Astro开发课程项目，接入Astro-DB后运行npm run dev报错。已尝试升级NodeJS（从v18.20到v21.17），使用最新版Astro，问题仍存在。

数据表代码 #

import { reference } from 'astro:content';
import { defineDb, defineTable, column } from 'astro:db';

// https://astro.build/db/config

const Teacher = defineTable({
  columns:{
    id : column.text({ primaryKey : true }),
    dni : column.text({ unique : true }),
    name : column.text({ unique : true }),
    departmentID : column.text({ references : () => Department.columns.id })
  }
})

const Department = defineTable({
  columns:{
    id : column.text({ primaryKey : true }),
    location : column.text({ unique : true }),
  }
})

const Student = defineTable({
  columns:{
    id : column.text({ primaryKey : true }),
    dni : column.text({ unique : true }),
    nia : column.text({ unique : true }),
    name : column.text({ unique : true }),
  }
})

const Class = defineTable({
  columns:{
    id : column.text({ primaryKey : true }),
    location : column.text({ unique : true }),
    teacherID : column.text({ references : () => Teacher.columns.id })
  }
})

const Subject = defineTable({
  columns:{
    id : column.text({ primaryKey : true }),
    location : column.text({ unique : true }),
    classId : column.text({references : () => Class.columns.id}),
  }
})

const Class_Student = defineTable ({
  columns : {
    classId : column.text({ references : () => Class.columns.id}),
    studenId : column.text({ references : () => Student.columns.id}),
  }
})

const Teacher_Student = defineTable({
  columns: {
    teacherId: column.text({ references : () => Teacher.columns.id }),
    studentId: column.text({ references : () => Student.columns.id }),
  },
})

export default defineDb({
  tables: {}
});

报错信息 #

Only URLs with a scheme in: file, data, and node are supported by the default ESM loader. Received protocol 'astro:'
  Stack trace:
    at new NodeError (node:internal/errors:405:5)
    at defaultLoad (node:internal/modules/esm/load:99:3)
    at ModuleLoader.moduleProvider (node:internal/modules/esm/loader:288:22)
    at #createModuleJob (node:internal/modules/esm/loader:312:17)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:251:17)

解决步骤 #

1. 移除无用导入 #

第一行import { reference } from 'astro:content';未被使用，且astro:content属于Astro内容集合模块，与Astro-DB无关。Node默认加载器无法处理astro:协议的裸导入，移除该行即可消除部分加载异常。

2. 注册数据表到DB配置 #

你定义了7张数据表，但defineDb的tables对象为空，Astro-DB无法识别这些表。需将所有表添加到tables中：

export default defineDb({
  tables: {
    Teacher,
    Department,
    Student,
    Class,
    Subject,
    Class_Student,
    Teacher_Student
  }
});

3. 调整表定义顺序修复潜在循环引用 #

Teacher表引用了Department，但Department在Teacher之后定义。虽然箭头函数延迟了引用，但调整顺序让被引用的表先定义，可避免潜在加载问题：

• 先定义Department，再定义Teacher
• 先定义Teacher，再定义Class
• 先定义Class，再定义Subject

调整后的表定义顺序示例：

const Department = defineTable({ ... });
const Teacher = defineTable({ ... });
const Student = defineTable({ ... });
const Class = defineTable({ ... });
const Subject = defineTable({ ... });
const Class_Student = defineTable({ ... });
const Teacher_Student = defineTable({ ... });

4. 确认Astro配置启用DB集成 #

检查astro.config.mjs，确保已添加@astrojs/db集成：

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

export default defineConfig({
  integrations: [db()],
});

报错原因说明 #

出现Received protocol 'astro:'错误，是因为Node默认ESM加载器无法识别Astro自定义的astro:协议模块。只有通过Astro CLI启动项目时，Astro的构建工具才会处理这类协议导入。移除无用的astro:content导入、确保所有Astro-DB表正确注册后，Astro就能正常处理模块加载，解决该报错。

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