Laravel主键使用指南及设置$incrementing为false后PostgreSQL环境下类型不匹配报错问题解决

问题原因 #

你遇到的错误本质是主键类型不匹配：虽然你给两个Model都设置了$incrementing = false，但Laravel默认的$keyType是int（整数类型）。当执行关联查询时，Laravel会把Atividade表中字符串格式的servico_id（比如'14.01'）自动转换为整数14，然后去匹配Servico表的字符串类型id，这就触发了PostgreSQL的类型不兼容错误——因为PostgreSQL不允许直接用整数和字符类型做比较。

解决方案 #

只需要在两个Model中添加$keyType = 'string';，明确告诉Laravel主键是字符串类型：

修改后的Atividade模型

class Atividade extends Model {
    use HasFactory;
    protected $with = ['servico'];
    protected $fillable = ['id', 'descricao'];
    public $incrementing = false;
    protected $keyType = 'string'; // 新增：指定主键为字符串类型
    /**
     * @return BelongsTo
     */
    public function servico(): BelongsTo {
        return $this->belongsTo(Servico::class, 'servico_id', 'id');
    }
}

修改后的Servico模型

class Servico extends Model {
    use HasFactory;
    protected $fillable = ['id', 'descricao'];
    protected $hidden = ['created_at', 'updated_at', 'deleted_at'];
    public $incrementing = false;
    protected $keyType = 'string'; // 新增：指定主键为字符串类型
}

添加这个配置后，Laravel就会保留主键的字符串格式，关联查询时会用字符串去匹配PostgreSQL的字符类型字段，不会再出现类型转换错误。

Laravel主键正确使用指南 #

这里整理几种常见主键场景的最佳实践：

• 默认自增整数主键

  • 无需额外配置，Laravel默认$incrementing = true、$keyType = 'int'
  • 数据库层面：PostgreSQL用serial/bigserial，MySQL用INT AUTO_INCREMENT作为主键类型

• 非自增字符串主键（如业务编码、自定义ID）

  • 必须设置public $incrementing = false;，关闭自增逻辑
  • 必须设置protected $keyType = 'string';，指定主键数据类型
  • 数据库层面：确保主键字段类型为varchar/text，并添加主键约束

• UUID主键

  • 使用Laravel自带的HasUuids trait，自动生成UUID主键
  • 配置示例：

    class Servico extends Model {
        use HasFactory, HasUuids;
        public $incrementing = false;
        protected $keyType = 'string';
    }
    

  • 数据库层面：主键字段设为varchar(36)（UUID固定长度）

• 关联查询注意事项

  • 外键字段的类型必须和关联模型的主键类型完全一致，尤其是在PostgreSQL这类强类型数据库中，类型不匹配会直接触发错误
  • 定义关联时，确保外键参数（第二个参数）和关联模型的主键（第三个参数）对应正确

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