[Objective] Maize production in Yunnan‑representative mountainous regions is strongly shaped by rugged terrain, fragmented cropland, and steep vertical climatic gradients, which drive pronounced spatial heterogeneity in soil nutrients and yield. Unlike homogeneous plains, yield variation here stems from the combined effects of soil fertility, climate, and topography rather than any single nutrient factor, making traditional statistics or isolated soil indicators inadequate. To this end, an interpretable machine learning framework integrating soil nutrients and spatial information was developed to enhance maize yield prediction and identify the dominant drivers of yield disparities across sub‑regions of such landscapes. [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 R² 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 R² 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 R² 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.