Laravel9 Eloquent hasOne/belongsTo关联仅返回ID未返回模型问题排查

出现该问题是因为关联方法名与数据表字段名重名，Eloquent 属性访问存在固定优先级：

• 优先匹配模型对应数据表的同名字段，存在则直接返回字段存储值
• 仅当不存在同名字段时，才会匹配同名关联方法，返回对应的关联模型实例

你的projects表本身就存在preview字段，存储的是关联files表的ID值，因此访问$projects->first()->preview时，Eloquent直接返回了字段存储的整数ID，不会触发你定义的preview()关联逻辑。

两种方案均可解决问题，推荐优先选择符合Laravel命名规范的方案2：

方案1：修改关联方法名（无需调整表结构） #

将Project模型中关联方法重命名为与字段不冲突的名称，例如previewFile：

// Project 模型
class Project extends Model
{
    public function previewFile(): BelongsTo
    {
        return $this->belongsTo(File::class, 'preview', 'id');
    }
}

同步修改控制器中的预加载、关联访问逻辑：

// 控制器查询
$projects = User::find($userId)->projects()->with(['user', 'previewFile'])->get();
// 访问关联
ddd($projects->first()->previewFile);

File模型中的反向关联无需调整，因为方法名previewProject本身不存在字段重名问题。

方案2：修改外键字段名（符合框架约定，推荐） #

按照Laravel默认的外键命名规范，将projects表的preview字段重命名为preview_id，迁移调整如下：

Schema::create('projects', static function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('code');
    $table->string('theme');
    $table->foreignId('discipline_id')->constrained('disciplines');
    $table->foreignId('user_id')->constrained('users');
    $table->string('external_id');
    // 原preview字段改为preview_id
    $table->foreignId('preview_id')->nullable()->constrained('files');
    $table->date('publish_date');
    $table->timestamps();
});

调整后关联定义可以简化，无需手动指定外键、主键参数，框架会自动识别：

// Project 模型
public function preview(): BelongsTo
{
    return $this->belongsTo(File::class);
}

// File 模型反向关联同步调整外键参数
public function previewProject(): HasOne
{
    return $this->hasOne(Project::class, 'preview_id', 'id');
}

该方案完全遵循Laravel的命名约定，后续开发不会再出现同名冲突问题，维护成本更低。

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