[Objective] Maize production in Yunnan province is strongly affected by its mountainous terrain, fragmented cropland, and pronounced vertical climatic gradients. These natural conditions lead to large spatial differences in soil nutrient status and maize yield across the province. In contrast to more homogeneous plain regions, yield variation in Yunnan is usually not controlled by one nutrient factor alone. It is more likely the combined result of soil fertility, climate background, terrain constraints, and other spatial environmental conditions. Therefore, using only traditional statistical methods or single soil indicators is often insufficient to explain regional yield differences. To address this issue, an interpretable machine learning approach that combines soil nutrient variables with spatial information was developed. The purpose was to improve maize yield prediction and, more importantly, to identify the main factors related to yield differences in different parts of Yunnan. [Methods] Soil testing and formula fertilization data from Yunnan province during 2005–2020 were combined with 5 km gridded maize yield data. Four soil nutrient indicators were selected, including soil organic matter, total nitrogen, available phosphorus, and available potassium. Longitude and latitude were also used as input variables. In this study, these two variables were not treated simply as location labels. They were included because spatial position can partly reflect regional environmental gradients that are difficult to describe using soil nutrient data alone, such as differences in elevation, heat and moisture conditions, terrain fragmentation, and cropping background. Based on these variables, particle swarm optimization was used to tune the main hyperparameters of the XGBoost model, forming a PSO-XGBoost yield prediction model. The optimized model was compared with LightGBM, CatBoost, random forest, support vector regression, and the original XGBoost model. Considering that nearby samples may share similar environmental conditions, random partitioning alone may overestimate model performance. Therefore, spatial block cross-validation was further used to examine the model's ability to predict yield under spatial separation. In addition, longitude and latitude were removed in an ablation experiment to test the contribution of spatial background information. Finally, SHAP was used to interpret the trained model, quantify the contribution of each variable, analyze the response of yield prediction to soil nutrients and spatial factors, and identify the dominant limiting factors in different maize-growing areas. [Results and Discussions] PSO-XGBoost showed the best performance among the tested models. Under random data partitioning, the model achieved an R2 of 0.91, indicating that it could effectively capture the relationship among soil nutrients, spatial background, and maize yield. Compared with LightGBM, CatBoost, and the unoptimized XGBoost model, PSO-XGBoost gave more accurate and stable predictions. This result suggested that particle swarm optimization improved the parameter configuration of XGBoost and made it more suitable for yield prediction in complex mountainous regions. Under spatial block cross-validation, the R2 decreased to 0.847. Although this value was lower than that obtained from random partitioning, it still showed good predictive performance under a stricter validation strategy. This also indicated that the model did not rely only on the similarity between neighboring samples, but retained a certain ability to predict yield in spatially separated areas. The ablation experiment further confirmed the importance of spatial information. After longitude and latitude were removed, the model R2 dropped sharply to 0.698. This decline showed that maize yield patterns in Yunnan cannot be well explained by soil nutrient indicators alone. Spatial variables probably contain information related to elevation-induced climatic differences, regional hydrothermal conditions, terrain fragmentation, and differences in the cropping environment. The SHAP results led to a similar conclusion. Longitude and latitude had relatively large contributions, suggesting that regional environmental gradients played an important role in yield formation. Among the soil nutrient variables, soil organic matter, total nitrogen, available phosphorus, and available potassium were all related to maize yield, but their roles differed across Yunnan. In some areas, yield was more closely associated with organic matter and nitrogen supply, while in others phosphorus or potassium appeared to be more limiting. This spatial difference suggested that the main constraints on maize production were not the same across the province. For this reason, a province-wide fertilization scheme would be difficult to apply effectively. Nutrient management in Yunnan should instead be adjusted according to local soil conditions and the environmental background of different mountainous regions. [Conclusions] Maize yield in Yunnan province is affected by both soil nutrient conditions and broader spatial environmental factors. Soil fertility is still an important basis for yield formation in mountainous farmland, but it does not explain the spatial yield differences on its own. By combining PSO-XGBoost with SHAP, this study provides a way to improve yield prediction while also tracing the main factors related to regional yield variation. The framework can be used to identify areas where nutrient constraints are more likely to occur, as well as areas where terrain, climate background, or other regional environmental factors may have a stronger influence. These results can support more targeted fertilization, cultivated land quality improvement, and sustainable maize production in the mountainous agricultural areas of Yunnan.