如何在Drupal中以编程方式添加实体内容？创建vehicle实体遇白屏求助

别担心，我帮你搞定这个问题！之前创建Node的经验确实没法直接套用到自定义实体上，白屏（White Page of Death）一般都是代码里藏着致命错误或者实体定义不符合规范导致的，咱们一步步来排查解决：

第一步：先揪出白屏的真实原因 #

白屏大多是因为PHP致命错误被屏蔽了，先开启错误提示才能看到问题本质：

• 临时在你的代码开头或者项目根目录的settings.php（Drupal环境）里添加以下代码：

// 开启Drupal调试模式
define('DRUPAL_DEBUG', true);
// 记录错误日志
define('Drupal\Core\Database\Database::setLogLevel(\Drupal\Core\Database\Database::LOG_ALL);');
// 直接显示错误信息
ini_set('display_errors', 1);

这样刷新页面后，要么能直接看到错误信息，要么能在sites/default/files/php-error.log日志文件里找到具体问题。

第二步：自定义Vehicle实体的正确代码示例 #

下面是一套完整的基础自定义Vehicle实体代码（适配Drupal 9/10），你可以对照修改：

1. 实体类文件（src/Entity/Vehicle.php） #

<?php

namespace Drupal\your_module_name\Entity;

use Drupal\Core\Entity\ContentEntityBase;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Field\BaseFieldDefinition;

/**
 * Defines the Vehicle entity.
 *
 * @ContentEntityType(
 *   id = "vehicle",
 *   label = @Translation("Vehicle"),
 *   base_table = "vehicle",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "name",
 *     "uuid" = "uuid",
 *   },
 *   handlers = {
 *     "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
 *     "list_builder" = "Drupal\your_module_name\VehicleListBuilder",
 *     "form" = {
 *       "add" = "Drupal\your_module_name\Form\VehicleForm",
 *       "edit" = "Drupal\your_module_name\Form\VehicleForm",
 *       "delete" = "Drupal\Core\Entity\ContentEntityDeleteForm",
 *     },
 *     "route_provider" = {
 *       "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
 *     },
 *   },
 *   links = {
 *     "canonical" = "/vehicle/{vehicle}",
 *     "add-form" = "/vehicle/add",
 *     "edit-form" = "/vehicle/{vehicle}/edit",
 *     "delete-form" = "/vehicle/{vehicle}/delete",
 *     "collection" = "/admin/content/vehicle",
 *   },
 * )
 */
class Vehicle extends ContentEntityBase {

  /**
   * {@inheritdoc}
   */
  public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
    $fields = parent::baseFieldDefinitions($entity_type);

    // 车辆名称（必填字段）
    $fields['name'] = BaseFieldDefinition::create('string')
      ->setLabel(t('Vehicle Name'))
      ->setDescription(t('The name of the vehicle.'))
      ->setRequired(true)
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'string',
        'weight' => -5,
      ])
      ->setDisplayOptions('form', [
        'type' => 'string_textfield',
        'weight' => -5,
      ])
      ->setDisplayConfigurable('view', true)
      ->setDisplayConfigurable('form', true);

    // 车辆类型
    $fields['type'] = BaseFieldDefinition::create('string')
      ->setLabel(t('Vehicle Type'))
      ->setDescription(t('The type of vehicle (car, truck, motorcycle, etc.).'))
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'string',
        'weight' => 0,
      ])
      ->setDisplayOptions('form', [
        'type' => 'string_textfield',
        'weight' => 0,
      ]);

    return $fields;
  }

}

2. 实体列表构建器（src/VehicleListBuilder.php） #

<?php

namespace Drupal\your_module_name;

use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Entity\EntityListBuilder;

/**
 * Defines a class to build a listing of Vehicle entities.
 */
class VehicleListBuilder extends EntityListBuilder {

  /**
   * {@inheritdoc}
   */
  public function buildHeader() {
    $header['id'] = $this->t('Vehicle ID');
    $header['name'] = $this->t('Name');
    $header['type'] = $this->t('Type');
    return $header + parent::buildHeader();
  }

  /**
   * {@inheritdoc}
   */
  public function buildRow(EntityInterface $entity) {
    /** @var \Drupal\your_module_name\Entity\Vehicle $entity */
    $row['id'] = $entity->id();
    $row['name'] = $entity->toLink();
    $row['type'] = $entity->get('type')->value;
    return $row + parent::buildRow($entity);
  }

}

3. 实体表单类（src/Form/VehicleForm.php） #

<?php

namespace Drupal\your_module_name\Form;

use Drupal\Core\Entity\ContentEntityForm;
use Drupal\Core\Form\FormStateInterface;

/**
 * Form controller for Vehicle edit forms.
 */
class VehicleForm extends ContentEntityForm {

  /**
   * {@inheritdoc}
   */
  public function save(array $form, FormStateInterface $form_state) {
    $entity = $this->entity;
    $status = $entity->save();

    $message = $status === SAVED_NEW
      ? $this->t('Created the %label Vehicle.', ['%label' => $entity->label()])
      : $this->t('Updated the %label Vehicle.', ['%label' => $entity->label()]);
    $this->messenger()->addStatus($message);

    $form_state->setRedirect('entity.vehicle.canonical', ['vehicle' => $entity->id()]);
  }

}

4. 模块配置文件（your_module_name.info.yml） #

name: 'Vehicle Entity'
type: module
description: 'Custom Vehicle entity module for managing vehicle records'
core_version_requirement: ^9 || ^10
package: Custom
dependencies:
  - drupal:system

第三步：排查常见的白屏触发点 #

对照你的代码，检查这几个最容易出错的地方：

• 命名空间错误：比如模块名是vehicle_manager，但代码里写的是Drupal\wrong_module_name\Entity，会直接导致类找不到的致命错误。
• 注释语法错误：@ContentEntityType注释里的括号、逗号、引号有没有写错，比如少了逗号或者引号没闭合，Drupal没法解析实体定义就会白屏。
• 缺失必要的Handler类：如果没创建VehicleListBuilder或者VehicleForm，访问实体页面时会找不到类，触发错误。
• 缓存没刷新：Drupal的实体定义依赖缓存，修改代码后一定要清缓存（用drush cr命令或者后台手动清除）。

第四步：快速调试流程 #

1. 先看错误日志，定位具体错误位置。
2. 检查实体类的命名空间和文件路径是否匹配。
3. 验证@ContentEntityType注释的语法是否正确。
4. 清空缓存后再测试。

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