GRANDstack初始化Neo4jGraphQL报Unknown directive @relation错误

云原生阿岚

2026-10-5

错误原因

你当前新建的GRANDstack项目依赖的是新版Neo4j GraphQL库，该版本将原有的@relation指令重命名为@relationship，同时调整了关系属性类型的定义规则。你通过infer-schema.js生成的schema是旧版neo4j-graphql-js包的语法，和新版库不兼容，因此运行时无法识别@relation指令。

解决方案

按以下规则修改你的GraphQL schema即可：

第一步：全局替换所有字段上的@relation指令为@relationship，原有name、direction参数无需调整，示例如下：
原写法：
```
recipes: [Recipe] @relation(name: "HAS", direction: IN)
```
替换后写法：
```
recipes: [Recipe] @relationship(name: "HAS", direction: IN)
```
第二步：调整带属性的关系类型定义规则：
旧版中用@relation装饰关系类型的写法，替换为用@relationshipProperties装饰，同时删除类型内的from、to字段定义，示例如下：
原写法：
```
type HAS @relation(name: "HAS") {
  from: Recipe!
  to: Incredient!
  amount: Float!
  unit: String!
}
```
替换后写法：
```
type HAS @relationshipProperties {
  amount: Float!
  unit: String!
}
```
第三步：在两侧关联字段的@relationship指令中新增properties参数绑定关系属性类型，同时删除原schema中声明的HAS_rel、HAS_OFFER_rel这类冗余的关系类型字段，示例如下：
原Recipe类型写法：
```
type Recipe {
  _id: ID!
  name: String!
  has: [Incredient] @relation(name: "HAS", direction: OUT)
  HAS_rel: [HAS]
}
```
替换后写法：
```
type Recipe {
  _id: ID!
  name: String!
  has: [Incredient] @relationship(name: "HAS", direction: OUT, properties: "HAS")
}
```
所有修改完成后重启API服务即可正常运行。