必须显式启用DataImportHandler，配置requestHandler、添加JAR包、同步SolrCloud节点；XML路径、命名空间、xpath需精准匹配；url/baseDir路径须正确；字段类型、空值、空白字符需手动处理。
solrconfig.xml 里必须显式启用 DataImportHandler
不配置 handler 就算 XML 文件放对位置、data-config.xml 写得再准，Solr 启动时根本不会加载 DIH，dataimport 请求直接 404。别指望它默认开启。
实操建议：
- 在
solrconfig.xml的<requestHandler>区域添加完整 handler 声明，不能只写类名，要带class="org.apache.solr.handler.dataimport.DataImportHandler" - 确保
lib目录下有solr-dataimporthandler-x.x.jar（版本需与 Solr 主版本一致），否则启动报NoClassDefFoundError: DataImportHandler - 如果用 SolrCloud，所有节点的
solrconfig.xml都得同步改，单点修改无效
data-config.xml 中 xml 文档结构决定 entity 的 forEach 和 xpath 写法
XML 不是 JSON，没有统一 schema；forEach 必须指向实际存在的重复节点路径，写错一级就一条数据都导不进来，且无明确报错，只会显示 Documents Processed: 0。
常见错误现象：
-
forEach="/root/item"却误写成/root/items/item（实际 XML 是<items><item>…</item></items>） - 忽略命名空间：含
xmlns的 XML，xpath必须用前缀，且要在<dataConfig>里声明xmlns:ns="http://example.com" - 属性值提取写成
xpath="title/text()"，但实际是<title lang="en">ABC</title>，正确应为xpath="@lang"或xpath="text()"
示例（简化）：
<entity name="book" dataSource="xml" forEach="/catalog/book"> <field column="id" xpath="id/text()"/> <field column="title" xpath="title/text()"/> <field column="price" xpath="price/@currency"/> </entity>
XML 数据源配置里 url 和 baseDir 容易路径失效
Solr 对 XML 源路径很敏感：既不自动补全，也不提示“文件未找到”，而是静默跳过或抛出模糊的 IOException，日志里只写 Unable to read: null。
使用场景和参数差异：
-
url用于远程 HTTP XML，必须是可被 Solr 服务器直连的地址（不是你本地浏览器能打开就行） -
baseDir用于本地文件，路径是 Solr 实例启动时的 工作目录，不是 core 目录，也不是 solr-home；常见误写成./conf/data.xml，实际应为/opt/solr/server/solr/mycore/conf/data.xml - Windows 下路径分隔符必须用正斜杠
/或双反斜杠\，单反斜杠会被当转义符处理
DataImportHandler 导入 XML 时字段类型和空值处理没默认规则
Solr 不会自动把 "123" 当成 int，也不会把空字符串 "" 或缺失节点当成 null；全靠 field 标签的 type 和 coerce 控制，漏配就存成字符串，查数字范围时查不到。
实操建议：
- 显式加
type="pint"/type="pfloat"等，且 schema.xml 中对应字段已定义 - 用
coerce="true"强制类型转换（如把 "0" 转 false），但失败时仍会存原字符串，不是丢弃 - 缺失字段默认留空，若想设默认值，加
default="N/A"；想跳过整条记录，得在transformer里写逻辑判断
容易被忽略的是：XML 节点含空白字符（换行、缩进）时，text() 取出来是 "
123
"，不 trim 就可能触发类型转换失败 —— 这种细节不会报错，只会让字段值异常。
